From 7e8dc9fa77c0b7a292a368f9c1e90a52d12ca0c0 Mon Sep 17 00:00:00 2001 From: teodoro Date: Mon, 3 Dec 2018 17:07:45 +0100 Subject: [PATCH 1/3] swagger files for the servers --- swagger/control/swagger.yaml | 152 +++++++++++++++++++++++++++++++++++ swagger/forward/swagger.yaml | 92 +++++++++++++++++++++ 2 files changed, 244 insertions(+) create mode 100644 swagger/control/swagger.yaml create mode 100644 swagger/forward/swagger.yaml diff --git a/swagger/control/swagger.yaml b/swagger/control/swagger.yaml new file mode 100644 index 0000000..5116a4a --- /dev/null +++ b/swagger/control/swagger.yaml @@ -0,0 +1,152 @@ +swagger: '2.0' +info: + title: Mailgun Relayery Control API + description: | + API for managing the authentication tokens and channel settings of remote instances. + version: "1.0.0" +host: mailgun.relayery.control.parquery.com +schemes: + - https +basePath: / +tags: +- name: "control" +paths: + /api/token: + put: + operationId: put_token + tags: + - control + description: | + updates the token associated with the descriptor. + + If there is already a token associated with the descriptor, the old token is overwritten with the new one. + parameters: + - name: named_token + in: body + schema: + $ref: "#/definitions/NamedToken" + required: true + consumes: + - application/json + responses: + 200: + description: signals that the token was accepted. + default: + description: contains an unexpected error. + delete: + operationId: delete_token + tags: + - control + description: | + removes the token associated with the descriptor. + parameters: + - name: descriptor + in: body + schema: + $ref: "#/definitions/Descriptor" + required: true + consumes: + - application/json + responses: + 200: + description: signals that the token was correctly erased. + 404: + description: signals that no token associated to the given descriptor exists. + default: + description: contains an unexpected error. + + /api/channel: + put: + operationId: put_channel + tags: + - control + description: | + updates the channel data associated with the descriptor. + + If there is already a channel associated with the descriptor, the old channel is overwritten with the new one. + parameters: + - name: descriptor + in: body + schema: + $ref: "#/definitions/Descriptor" + required: true + - name: channel + in: body + schema: + $ref: "#/definitions/Channel" + required: true + consumes: + - application/json + responses: + 200: + description: signals that the channel was accepted. + default: + description: contains an unexpected error. + delete: + operationId: delete_channel + tags: + - control + description: | + removes the channel associated with the descriptor. + parameters: + - name: descriptor + in: body + schema: + $ref: "#/definitions/Descriptor" + required: true + consumes: + - application/json + responses: + 200: + description: signals that the channel was correctly erased. + 404: + description: signals that no channel associated to the given descriptor was found. + default: + description: contains an unexpected error. + +definitions: + Token: + description: is a string authenticating the sender of an HTTP request. + type: string + example: RBbPYhmPXurT8nM5TAJpPOcHMaFkJblA62mr6MCvpF4oVa6cy + + Descriptor: + description: uniquely identifies an instance. + type: string + example: client-1/pipeline-3 + + Entity: + description: contains the email address and optionally the name of an entity. + type: object + properties: + email: + type: string + example: name@domain.com + name: + type: string + example: John Doe + required: + - email + + + Channel: + description: contains the channel settings for messages received by an instance. + type: object + properties: + sender: + $ref: "#/definitions/Entity" + recipients: + type: array + items: + $ref: "#/definitions/Entity" + cc: + type: array + items: + $ref: "#/definitions/Entity" + bcc: + type: array + items: + $ref: "#/definitions/Entity" + required: + - sender + - recipients diff --git a/swagger/forward/swagger.yaml b/swagger/forward/swagger.yaml new file mode 100644 index 0000000..cc8bc58 --- /dev/null +++ b/swagger/forward/swagger.yaml @@ -0,0 +1,92 @@ +swagger: '2.0' +info: + title: Mailgun Relayery Forward Server API + description: | + API for the server listening to the remote instances' push of messages and forwarding them to MailGun. + + The instances need to provide an authentication token upon pushing to this server. + version: "1.0.0" +host: mailgun.relayery.forward.parquery.com +schemes: + - https +basePath: / +tags: +- name: "forward" +paths: + /api/message: + put: + operationId: put_message + tags: + - forward + description: | + sends a message to the server, which forwards it to the MailGun API. + + The given (descriptor, token) pair are authenticated first. + The message's metadata is determined by the channel information from the Control server. + parameters: + - name: descriptor + in: body + schema: + $ref: "#/definitions/Descriptor" + required: true + - name: token + in: body + schema: + $ref: "#/definitions/Token" + required: true + - name: message + in: body + schema: + $ref: "#/definitions/Message" + required: true + consumes: + - application/json + responses: + 200: + description: signals that the message was correctly forwarded to MailGun. + 401: + description: signals that the request token is invalid. + 404: + description: signals that the descriptor is unknown. + default: + description: contains an unexpected error. + +definitions: + Token: + description: is a string authenticating the sender of an HTTP request. + type: string + example: RBbPYhmPXurT8nM5TAJpPOcHMaFkJblA62mr6MCvpF4oVa6cy + + Descriptor: + description: uniquely identifies an instance. + type: string + example: client-1/pipeline-3 + + Entity: + description: contains the email address and optionally the name of an entity. + type: object + properties: + email: + type: string + example: name@domain.com + name: + type: string + example: John Doe + required: + - email + + Message: + description: represents a message to be forwarded. + type: object + properties: + subject: + description: contains the text to be used as the email's subject. + type: string + example: "broken pipeline observed" + content: + description: contains the text to be used as the email's content. + type: string + example: "A broken pipeline was observed the 10/12/2018 at 14:37. Please contact the system operator." + required: + - timestamp + - content From 169f9fea2ddec8252cfaf787ba331108ebc70409 Mon Sep 17 00:00:00 2001 From: teodoro Date: Tue, 4 Dec 2018 17:38:51 +0100 Subject: [PATCH 2/3] integrated PR feedbacks --- swagger/control/swagger.yaml | 177 ++++++++++++++++-------- swagger/{forward => relay}/swagger.yaml | 45 +++--- 2 files changed, 138 insertions(+), 84 deletions(-) rename swagger/{forward => relay}/swagger.yaml (62%) diff --git a/swagger/control/swagger.yaml b/swagger/control/swagger.yaml index 5116a4a..050168b 100644 --- a/swagger/control/swagger.yaml +++ b/swagger/control/swagger.yaml @@ -4,41 +4,41 @@ info: description: | API for managing the authentication tokens and channel settings of remote instances. version: "1.0.0" -host: mailgun.relayery.control.parquery.com schemes: - https basePath: / tags: - name: "control" paths: - /api/token: + + /api/channel: put: - operationId: put_token + operationId: put_channel tags: - control description: | - updates the token associated with the descriptor. + updates the channel uniquely identified by a descriptor. - If there is already a token associated with the descriptor, the old token is overwritten with the new one. + If there is already a channel associated with the descriptor, the old channel is overwritten with the new one. parameters: - - name: named_token + - name: channel in: body schema: - $ref: "#/definitions/NamedToken" + $ref: "#/definitions/Channel" required: true consumes: - application/json responses: 200: - description: signals that the token was accepted. + description: signals that the channel was accepted. default: description: contains an unexpected error. delete: - operationId: delete_token + operationId: delete_channel tags: - control description: | - removes the token associated with the descriptor. + removes the channel associated with the descriptor. parameters: - name: descriptor in: body @@ -49,69 +49,58 @@ paths: - application/json responses: 200: - description: signals that the token was correctly erased. + description: signals that the channel was correctly erased. 404: - description: signals that no token associated to the given descriptor exists. + description: signals that no channel associated to the given descriptor was found. default: description: contains an unexpected error. - /api/channel: - put: - operationId: put_channel + /api/list_channels: + get: + operationId: list_channels tags: - control - description: | - updates the channel data associated with the descriptor. - - If there is already a channel associated with the descriptor, the old channel is overwritten with the new one. + description: lists the available channels information. parameters: - - name: descriptor - in: body - schema: - $ref: "#/definitions/Descriptor" - required: true - - name: channel - in: body - schema: - $ref: "#/definitions/Channel" - required: true + - name: page + in: query + description: specifies the index of a page. The default is 1 (first page). + type: integer + format: int32 + - name: per_page + in: query + description: specifies a desired number of items per page. The default is 100. + type: integer + format: int32 consumes: - application/json + produces: + - application/json responses: 200: description: signals that the channel was accepted. - default: - description: contains an unexpected error. - delete: - operationId: delete_channel - tags: - - control - description: | - removes the channel associated with the descriptor. - parameters: - - name: descriptor - in: body schema: - $ref: "#/definitions/Descriptor" - required: true - consumes: - - application/json - responses: - 200: - description: signals that the channel was correctly erased. - 404: - description: signals that no channel associated to the given descriptor was found. + $ref: "#/definitions/ChannelsPage" default: description: contains an unexpected error. definitions: Token: - description: is a string authenticating the sender of an HTTP request. - type: string - example: RBbPYhmPXurT8nM5TAJpPOcHMaFkJblA62mr6MCvpF4oVa6cy + description: defines the authentication token for a descriptor. + type: object + properties: + descriptor: + $ref: "#/definitions/Descriptor" + token: + description: is a string authenticating the sender of an HTTP request. + type: string + example: RBbPYhmPXurT8nM5TAJpPOcHMaFkJblA62mr6MCvpF4oVa6cy + required: + - descriptor + - token Descriptor: - description: uniquely identifies an instance. + description: identifies a channel. type: string example: client-1/pipeline-3 @@ -128,11 +117,14 @@ definitions: required: - email - Channel: - description: contains the channel settings for messages received by an instance. + description: defines the messaging channel. type: object properties: + descriptor: + $ref: "#/definitions/Descriptor" + token: + $ref: "#/definitions/Token" sender: $ref: "#/definitions/Entity" recipients: @@ -147,6 +139,81 @@ definitions: type: array items: $ref: "#/definitions/Entity" + min_period: + description: is the minimum push period frequency for a channel, in seconds. + type: number + format: float + max_size: + description: indicates the maximum allowed size of the message, in bytes. + type: integer + format: int64 required: + - descriptor + - token - sender - recipients + - min_period + - max_size + + Rel: + description: defines the link relation information about a page. + type: object + properties: + href: + description: contains a URL. + type: string + required: + - href + + OptionalRel: + description: defines the link relation information about a page that might not exist. + type: object + properties: + href: + description: contains a URL. + type: string + + Rels: + description: contains information about a set of pages related to a page. + type: object + properties: + first: + $ref: "#/definitions/Rel" + last: + $ref: "#/definitions/Rel" + prev: + $ref: "#/definitions/OptionalRel" + next: + $ref: "#/definitions/OptionalRel" + required: + - first + - last + - prev + - next + + ChannelsPage: + description: defines the response to the list_channels endpoint. + type: object + properties: + page: + description: specifies the index of the page. + type: integer + format: int32 + per_page: + description: specifies the number of items per page. + type: integer + format: int32 + channels: + description: contains the channel data. + type: array + items: + $ref: "#/definitions/Channel" + rels: + $ref: "#/definitions/Rels" + required: + - page + - per_page + - channels + - rels + + diff --git a/swagger/forward/swagger.yaml b/swagger/relay/swagger.yaml similarity index 62% rename from swagger/forward/swagger.yaml rename to swagger/relay/swagger.yaml index cc8bc58..813fdda 100644 --- a/swagger/forward/swagger.yaml +++ b/swagger/relay/swagger.yaml @@ -1,36 +1,36 @@ swagger: '2.0' info: - title: Mailgun Relayery Forward Server API + title: Mailgun Relayery Relay Server API description: | - API for the server listening to the remote instances' push of messages and forwarding them to MailGun. + relays messages coming from multiple message channels to a single Mailgun email channel. - The instances need to provide an authentication token upon pushing to this server. + The clients need to authenticate by basic auth specifying the channel descriptor as the + user name and the assigned API token as the password. version: "1.0.0" -host: mailgun.relayery.forward.parquery.com schemes: - https basePath: / tags: -- name: "forward" +- name: "relay" paths: /api/message: - put: + post: operationId: put_message tags: - - forward + - relay description: | - sends a message to the server, which forwards it to the MailGun API. + sends a message to the server, which relays it to the MailGun API. The given (descriptor, token) pair are authenticated first. The message's metadata is determined by the channel information from the Control server. parameters: - - name: descriptor - in: body + - name: X-descriptor + in: header schema: $ref: "#/definitions/Descriptor" required: true - - name: token - in: body + - name: X-token + in: header schema: $ref: "#/definitions/Token" required: true @@ -43,7 +43,7 @@ paths: - application/json responses: 200: - description: signals that the message was correctly forwarded to MailGun. + description: signals that the message was correctly relayed to MailGun. 401: description: signals that the request token is invalid. 404: @@ -58,25 +58,12 @@ definitions: example: RBbPYhmPXurT8nM5TAJpPOcHMaFkJblA62mr6MCvpF4oVa6cy Descriptor: - description: uniquely identifies an instance. + description: identifies a channel. type: string example: client-1/pipeline-3 - Entity: - description: contains the email address and optionally the name of an entity. - type: object - properties: - email: - type: string - example: name@domain.com - name: - type: string - example: John Doe - required: - - email - Message: - description: represents a message to be forwarded. + description: represents a message to be relayed. type: object properties: subject: @@ -88,5 +75,5 @@ definitions: type: string example: "A broken pipeline was observed the 10/12/2018 at 14:37. Please contact the system operator." required: - - timestamp + - subject - content From fdd13213e3ac2a122dfdfdbafbecc7688cb9eecc Mon Sep 17 00:00:00 2001 From: teodoro Date: Fri, 7 Dec 2018 10:48:26 +0100 Subject: [PATCH 3/3] removing rels --- swagger/control/swagger.yaml | 70 +++++++++++------------------------- swagger/relay/swagger.yaml | 2 +- 2 files changed, 21 insertions(+), 51 deletions(-) diff --git a/swagger/control/swagger.yaml b/swagger/control/swagger.yaml index 050168b..d36d860 100644 --- a/swagger/control/swagger.yaml +++ b/swagger/control/swagger.yaml @@ -1,8 +1,8 @@ swagger: '2.0' info: - title: Mailgun Relayery Control API + title: Control API description: | - API for managing the authentication tokens and channel settings of remote instances. + API for managing the channels. version: "1.0.0" schemes: - https @@ -10,7 +10,6 @@ basePath: / tags: - name: "control" paths: - /api/channel: put: operationId: put_channel @@ -30,7 +29,7 @@ paths: - application/json responses: 200: - description: signals that the channel was accepted. + description: signals that the channel update was accepted. default: description: contains an unexpected error. delete: @@ -78,7 +77,7 @@ paths: - application/json responses: 200: - description: signals that the channel was accepted. + description: serves the channel information list. schema: $ref: "#/definitions/ChannelsPage" default: @@ -86,18 +85,9 @@ paths: definitions: Token: - description: defines the authentication token for a descriptor. - type: object - properties: - descriptor: - $ref: "#/definitions/Descriptor" - token: - description: is a string authenticating the sender of an HTTP request. - type: string - example: RBbPYhmPXurT8nM5TAJpPOcHMaFkJblA62mr6MCvpF4oVa6cy - required: - - descriptor - - token + description: is a string authenticating the sender of an HTTP request. + type: string + example: RBbPYhmPXurT8nM5TAJpPOcHMaFkJblA62mr6MCvpF4oVa6cy Descriptor: description: identifies a channel. @@ -144,7 +134,7 @@ definitions: type: number format: float max_size: - description: indicates the maximum allowed size of the message, in bytes. + description: indicates the maximum allowed size of the request, in bytes. type: integer format: int64 required: @@ -155,16 +145,6 @@ definitions: - min_period - max_size - Rel: - description: defines the link relation information about a page. - type: object - properties: - href: - description: contains a URL. - type: string - required: - - href - OptionalRel: description: defines the link relation information about a page that might not exist. type: object @@ -173,32 +153,18 @@ definitions: description: contains a URL. type: string - Rels: - description: contains information about a set of pages related to a page. - type: object - properties: - first: - $ref: "#/definitions/Rel" - last: - $ref: "#/definitions/Rel" - prev: - $ref: "#/definitions/OptionalRel" - next: - $ref: "#/definitions/OptionalRel" - required: - - first - - last - - prev - - next - ChannelsPage: - description: defines the response to the list_channels endpoint. + description: lists channels in a paginated manner. type: object properties: page: description: specifies the index of the page. type: integer format: int32 + page_count: + description: specifies the number of pages available. + type: integer + format: int32 per_page: description: specifies the number of items per page. type: integer @@ -208,12 +174,16 @@ definitions: type: array items: $ref: "#/definitions/Channel" - rels: - $ref: "#/definitions/Rels" + prev: + $ref: "#/definitions/OptionalRel" + next: + $ref: "#/definitions/OptionalRel" required: - page + - page_count - per_page - channels - - rels + - prev + - next diff --git a/swagger/relay/swagger.yaml b/swagger/relay/swagger.yaml index 813fdda..40baff3 100644 --- a/swagger/relay/swagger.yaml +++ b/swagger/relay/swagger.yaml @@ -1,6 +1,6 @@ swagger: '2.0' info: - title: Mailgun Relayery Relay Server API + title: Relay Server API description: | relays messages coming from multiple message channels to a single Mailgun email channel.