openapi.yaml

swagger: '2.0'

info:
  version: "0.0.1"
  title: SMSender API

host: localhost:8080
basePath: /api
tags:
  - name: messages
    description: |
      #### Message Status

      | STATUS | DESCRIPTION |
      |---|---|
      | accepted | Received your API request to send a message |
      | queued | The message is queued to be sent out |
      | sending | The message is in the process of dispatching to the upstream carrier |
      | failed | The message could not be sent to the upstream carrier |
      | sent | The message was successfully accepted by the upstream carrie |
      | unknown | Received an undocumented status code from the upstream carrier |
      | undelivered | Received that the message was not delivered from the upstream carrier |
      | delivered | Received confirmation of message delivery from the upstream carrier |
  - name: errors
    description: |
      All errors will return with the following JSON body:
      ```json
      {
        "error": "ascii_error_code",
        "error_description": "Human-readable ASCII text providing additional information, used to assist the client developer in understanding the error that occurred."
      }
      ```
schemes:
  - http
  - https
consumes:
  - application/json
produces:
  - application/json
paths:
  /messages:
    get:
      tags:
        - messages
      description: |
        Gets Message objects.
      parameters:
        - in: query
          name: since
          description: The since of the range (UnixMicro)
          type: string
        - in: query
          name: until
          description: The until of the range (UnixMicro)
          type: string
        - in: query
          name: to
          description: The destination phone number (E.164 format)
          type: string
        - in: query
          name: status
          description: The status of the message
          type: string
        - in: query
          name: limit
          description: The Maximum number of objects that may be returned
          type: integer
      responses:
        200:
          description: OK
          schema:
            type: object
            properties:
              data:
                title: ArrayOfMessage
                type: array
                items:
                  $ref: '#/definitions/Message'
        400:
          description: Bad request
          schema:
            $ref: '#/definitions/Error'
    post:
      tags:
        - messages
      description: |
        Send Message.
      parameters:
        - in: body
          name: body
          description: Message
          required: false
          schema:
            type: object
            properties:
              to:
                type: array
                items:
                  type: string
                  description: The destination phone number (E.164 format)
              from:
                type: string
                description: Sender Id (phone number or alphanumeric)
              body:
                type: string
                description: The text of the message
              async:
                type: boolean
                description: Enable a background sending mode that is optimized for bulk sending
            required:
              - to
              - body
      responses:
        200:
          description: OK
          schema:
            type: object
            properties:
              data:
                title: ArrayOfMessage
                type: array
                items:
                  $ref: '#/definitions/Message'
        400:
          description: Bad request
          schema:
            $ref: '#/definitions/Error'
  /messages/byIds:
    get:
      tags:
        - messages
      description: |
        Gets specific Message objects.
      parameters:
        - in: query
          name: ids
          description: Message Id of array
          required: true
          type: array
          items:
            type: string
          collectionFormat: multi
      responses:
        200:
          description: OK
          schema:
            type: object
            properties:
              data:
                title: ArrayOfMessage
                type: array
                items:
                  $ref: '#/definitions/Message'
        400:
          description: Bad request
          schema:
            $ref: '#/definitions/Error'
  /routes:
    get:
      tags:
        - routes
      description: |
        Gets Route objects.
      responses:
        200:
          description: OK
          schema:
            type: object
            properties:
              data:
                title: ArrayOfRoute
                type: array
                items:
                  $ref: '#/definitions/Route'
              providers:
                title: ArrayOfProvider
                type: array
                items:
                  $ref: '#/definitions/Provider'
    post:
      tags:
        - routes
      description: |
        Create a Route.
      parameters:
        - in: body
          name: body
          description: Route
          required: true
          schema:
            $ref: "#/definitions/Route"
      responses:
        200:
          description: OK
          schema:
            $ref: "#/definitions/Route"
        400:
          description: Bad request (bad_request, route_already_exists, provider_not_found)
          schema:
            $ref: '#/definitions/Error'
    put:
      tags:
        - routes
      description: |
        Reorder a Route in a route list.
      parameters:
        - in: body
          name: body
          required: true
          schema:
            $ref: "#/definitions/Reorder"
      responses:
        200:
          description: Ok
          schema:
            type: object
            properties:
              data:
                title: ArrayOfRoute
                type: array
                items:
                  $ref: '#/definitions/Route'
              providers:
                title: ArrayOfProvider
                type: array
                items:
                  $ref: '#/definitions/Provider'
        400:
          description: Bad request
          schema:
            $ref: '#/definitions/Error'
  /routes/{route}:
    put:
      tags:
        - routes
      description: |
        Replace a Route.
      parameters:
        - name: route
          in: path
          description: Name of Route.
          required: true
          type: string
        - in: body
          name: body
          description: Message
          required: true
          schema:
            $ref: "#/definitions/Route"
      responses:
        200:
          description: OK
          schema:
            $ref: "#/definitions/Route"
        400:
          description: Bad request
          schema:
            $ref: '#/definitions/Error'
        404:
          description: Route not found
          schema:
            $ref: '#/definitions/Error'
    delete:
      tags:
        - routes
      description: |
        Delete a Route.
      parameters:
        - name: route
          in: path
          description: Name of Route.
          required: true
          type: string
      responses:
        204:
          description: Ok
        400:
          description: Bad request
          schema:
            $ref: '#/definitions/Error'
        404:
          description: Route not found
          schema:
            $ref: '#/definitions/Error'
definitions:
  Message:
    properties:
      id:
        type: string
        description: Message Id
      to:
        type: string
        description: The destination phone number (E.164 format)
      from:
        type: string
        description: Sender Id (phone number or alphanumeric)
      body:
        type: string
        description: The text of the message
      async:
        type: boolean
        description: Enable a background sending mode that is optimized for bulk sending
      route:
        type: string
      provider:
        type: string
      provider_message_id:
        description: The upstream carrier's message id
        type: string
      steps:
        type: object
      status:
        type: string
        description: The status of the message
      created_time:
        type: string
        description: Message created time
      updated_time:
        type: string
        description: Message updated time
  Route:
    type: object
    properties:
      name:
        type: string
      pattern:
        type: string
        description: Phone number regular expression to be matched with a provider
      provider:
        type: string
        description: Provider name
      from:
        type: string
        description: Sender Id (phone number or alphanumeric)
      is_active:
        type: boolean
    required:
      - name
      - pattern
      - provider
  Reorder:
    type: object
    properties:
      range_start:
        type: integer
        description: |
          The position of the first route to be reordered.
      range_length:
        type: integer
        description: |
          The amount of routes to be reordered. Defaults to 1 if not set.
      insert_before:
        type: integer
        description: |
          The position where the routes should be inserted.
  Provider:
    type: object
    properties:
      name:
        type: string
        description: Provider name
  Error:
    type: object
    properties:
      error:
        type: string
      error_description:
        type: string
    required:
     - error