swagger files for the servers

swagger/control/swagger.yaml

@@ -0,0 +1,219 @@
+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"
+schemes:
+  - https
+basePath: /
+tags:
+- name: "control"
+paths:
+
+  /api/channel:
+    put:
+      operationId: put_channel
+      tags:
+        - control
+      description: |
+        updates the channel uniquely identified by a descriptor.
+
+        If there is already a channel associated with the descriptor, the old channel is overwritten with the new one.
+      parameters:
+        - 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.
+
+  /api/list_channels:
+    get:
+      operationId: list_channels
+      tags:
+        - control
+      description: lists the available channels information.
+      parameters:
+        - 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.
+          schema:
+            $ref: "#/definitions/ChannelsPage"
+        default:
+          description: contains an unexpected error.
+
+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
+
+  Descriptor:
+    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
+
+  Channel:
+    description: defines the messaging channel.
+    type: object
+    properties:
+      descriptor:
+        $ref: "#/definitions/Descriptor"
+      token:
+        $ref: "#/definitions/Token"
+      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"
+      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
+
+

swagger/relay/swagger.yaml

@@ -0,0 +1,79 @@
+swagger: '2.0'
+info:
+  title: Mailgun Relayery Relay Server API
+  description: |
+    relays messages coming from multiple message channels to a single Mailgun email channel.
+
+    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"
+schemes:
+  - https
+basePath: /
+tags:
+- name: "relay"
+paths:
+  /api/message:
+    post:
+      operationId: put_message
+      tags:
+        - relay
+      description: |
+        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: X-descriptor
+          in: header
+          schema:
+            $ref: "#/definitions/Descriptor"
+          required: true
+        - name: X-token
+          in: header
+          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 relayed 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: identifies a channel.
+    type: string
+    example: client-1/pipeline-3
+
+  Message:
+    description: represents a message to be relayed.
+    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:
+      - subject
+      - content