openapi.yaml

openapi: 3.0.2
info:
  title: Voluble API
  version: "1.0"
  description: >
    This is the OpenAPI specification for the Voluble messaging service API.

    Current API status:![OpenAPI Validity
    Status](http://validator.swagger.io/validator?url=https://raw.githubusercontent.com/calmcl1/voluble/master/openapi.yaml)
  contact:
    email: mail@callum-mclean.co.uk
    name: Cal McLean
servers:
  - url: "https://voluble-poc.herokuapp.com/v1"
externalDocs:
  description: Find out more about the Voluble architecture
  url: "https://voluble.gitbook.io/docs/"
tags:
  - name: Contacts
    description: All operations regarding Contact objects
  - name: Messages
    description: All operations regarding Message objects
  - name: Services
    description: All operations regarding Service/plugin objects
  - name: Servicechains
    description: All operations regarding Servicechain objects
  - name: Organizations
    description: All operations regarding Organization objects
components:
  responses:
    "400":
      description: Data supplied is invalid
    "404":
      description: No object found with the specified ID
    "410":
      description: Object with specified ID has already been deleted
    "500":
      description: Internal server error
  parameters:
    org-id:
      in: path
      name: org-id
      required: true
      example: c616d114-4f68-4dba-b976-cd5ae0aa359d
      allowEmptyValue: false
      schema:
        type: string
        nullable: false
        format: uuid
        pattern: >-
          ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}
      description: The Organization that owns this resource
  schemas:
    Contact:
      type: object
      properties:
        id:
          type: string
          description: UUID for this Contact within Voluble
          example: c616d114-4f68-4dba-b976-cd5ae0aa359d
          readOnly: true
          nullable: false
          format: uuid
          pattern: >-
            ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}
        title:
          type: string
          description: The title of the Contact (Mr/Mrs, etc.)
          example: Mr
          nullable: false
        first_name:
          type: string
          description: The first name of the Contact
          example: John
          nullable: false
        surname:
          type: string
          description: The surname of the Contact
          example: Cleese
          nullable: false
        email_address:
          type: string
          description: >-
            The email address for the contact, that will be passed to Auth0 for
            authentication
          example: myname@emailprovider.com
          nullable: false
        phone_number:
          type: string
          description: >-
            The E164-formatted phone number for the Contact that will be used
            for fallback SMS messaging
          example: "+442071838750"
          nullable: false
        OrganizationId:
          type: string
          description: >-
            The UUID of the Organization within Voluble that this Contact
            belongs to
          example: c616d114-4f68-4dba-b976-cd5ae0aa359d
          nullable: false
        ServicechainId:
          type: string
          description: >-
            The UUID of the default servicechain that will be used to send
            messages to the Contact
          nullable: false
          example: c616d114-4f68-4dba-b976-cd5ae0aa359d
    Message:
      type: object
      properties:
        id:
          type: string
          description: The UUID of the Message within Voluble
          readOnly: true
          example: c616d114-4f68-4dba-b976-cd5ae0aa359d
          nullable: false
        body:
          type: string
          description: The text content of the Message that is transmitted
          example: Hi! Voluble has delivered this message to you!
          nullable: true
        ServicechainID:
          type: string
          description: >-
            The UUID of the of the Servicechain within Voluble to be used to
            send the message
          example: c616d114-4f68-4dba-b976-cd5ae0aa359d
          nullable: false
        contact:
          type: string
          nullable: false
          description: >-
            The UUID of the Contact related to this message (i.e. sender or
            recipient) within Voluble
          example: c616d114-4f68-4dba-b976-cd5ae0aa359d
        is_reply_to:
          type: string
          nullable: true
          description: >-
            The UUID of the Message that this Message is a reply to. NULL if
            this is message was not a reply to a previous message
          example: c616d114-4f68-4dba-b976-cd5ae0aa359d
        user:
          type: string
          nullable: true
          description: >-
            The UUID of the User that send the Message, if this is an outbound Message.
            Otherwise, null.
          readOnly: true
          example: c616d114-4f68-4dba-b976-cd5ae0aa359d
        direction:
          type: string
          enum:
            - INBOUND
            - OUTBOUND
          description: >-
            Describes which direction the message was moving (i.e. who sent the
            message): `OUTBOUND` if the message was sent from Voluble to a
            Contact; `INBOUND` if the message was sent by a Contact to Voluble.
          nullable: false
          readOnly: true
        sent_time:
          type: number
          nullable: false
          description: The UNIX timestamp of when the message was sent.
          example: 1568548864
          readOnly: true
        message_state:
          type: string
          description: >-
            Describes the current state of the message - `SENT`, `FAILED`,
            `DELIVERED`, etc.
          nullable: false
          readOnly: true
          enum:
            - MSG_PENDING
            - MSG_SENDING
            - MSG_DELIVERED_SERVICE
            - MSG_DELIVERED_USER
            - MSG_READ
            - MSG_REPLIED
            - MSG_FAILED
            - MSG_ARRIVED
    Organization:
      type: object
      properties:
        id:
          type: string
          nullable: false
          readOnly: true
          description: The UUID of the Organization within Voluble
          example: c616d114-4f68-4dba-b976-cd5ae0aa359d
        name:
          type: string
          description: The human-friendly name of the Organization
          nullable: false
          example: MyCorp
        phone_number:
          type: string
          description: >-
            The E164-formatted phone number where all SMSs from Voluble on
            behalf of the Organization will originate
          nullable: false
          example: "+442071838750"
    Service:
      type: object
      properties:
        id:
          type: string
          nullable: false
          readOnly: true
          description: The UUID of the Service within Voluble
          example: c616d114-4f68-4dba-b976-cd5ae0aa359d
        name:
          type: string
          nullable: false
          description: The human-readable name of the Service that can send Messages
          example: My Awesome Messaging Service
        directory_name:
          type: string
          nullable: false
          description: >-
            The name of the subdirectory below the global Voluble plugin
            directory where the plugins' `plugin.js` is located.
          example: awesome-msg-svc
    ServiceInServicechain:
      type: object
      properties:
        id:
          type: string
          nullable: false
          readOnly: true
          description: The UUID of the ServiceInServicechain within Voluble
          example: c616d114-4f68-4dba-b976-cd5ae0aa359d
        service:
          type: string
          nullable: false
          description: >-
            The UUID of the Service with Voluble to be used at this priority in
            the Servicechain
          example: c616d114-4f68-4dba-b976-cd5ae0aa359d
        priority:
          type: integer
          nullable: false
          example: 0
    Servicechain:
      type: object
      properties:
        id:
          type: string
          nullable: false
          readOnly: true
          description: The UUID of the Servicechain within Voluble
          example: c616d114-4f68-4dba-b976-cd5ae0aa359d
        services:
          type: array
          items:
            $ref: "#/components/schemas/ServiceInServicechain"
          maxItems: 10
        name:
          type: string
          nullable: false
          description: The human-readable name of the Servicechain
          example: Online-only SC
    User:
      type: object
      properties:
        id:
          type: string
          nullable: false
          readOnly: true
          description:
            The Auth0-generated ID of the corresponding user in Auth0 for
            authentication management.
          example: auth0|c616d114-4f68-4dba-b976-cd5ae0aa359d
  securitySchemes:
    jwt:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: "A JWT bearer token generated by Auth0, representing the User."
paths:
  /orgs/{org-id}/users:
    parameters:
      - $ref: "#/components/parameters/org-id"
    get:
      tags:
        - Users
      description: >-
        Returns a list of the Users available in the Organization, starting at `offset`.
      security:
        - jwt: []
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/User"
        "500":
          $ref: "#/components/responses/500"

  /orgs/{org-id}/contacts:
    parameters:
      - $ref: "#/components/parameters/org-id"
    get:
      tags:
        - Contacts
      summary: >-
        Returns a list of the first 100 Contacts available to the User in the
        Organization
      description: >-
        Returns a list of the first 100 Contacts available to the User in the
        Organization, starting at `offset`.
      security:
        - jwt: []
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Contact"
                maxItems: 100
        "500":
          $ref: "#/components/responses/500"
    post:
      tags:
        - Contacts
      summary: Allows the creation of a new Contact
      security:
        - jwt: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Contact"
      responses:
        "201":
          description: "OK: User created"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Contact"
          links:
            GetContactById:
              operationId: getContact
              parameters:
                contact_id: "$response.body#/id"
        "400":
          $ref: "#/components/responses/400"
        "500":
          $ref: "#/components/responses/500"
  /orgs/{org-id}/contacts/{contact_id}:
    parameters:
      - $ref: "#/components/parameters/org-id"
      - name: contact_id
        in: path
        required: true
        description: The ID of the Contact to manipulate
        schema:
          type: string
    get:
      tags:
        - Contacts
      operationId: getContact
      summary: Retrieves a particular Contact
      security:
        - jwt: []
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Contact"
        "404":
          $ref: "#/components/responses/404"
        "500":
          $ref: "#/components/responses/500"
    put:
      tags:
        - Contacts
      operationId: modifyContact
      summary: Modifies a specific contact
      security:
        - jwt: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Contact"
      responses:
        "200":
          description: Contact modified successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Contact"
          links:
            GetContactById:
              operationId: getContact
              parameters:
                contact_id: "$response.body#/id"
        "400":
          $ref: "#/components/responses/400"
        "404":
          $ref: "#/components/responses/404"
        "500":
          $ref: "#/components/responses/500"
    delete:
      tags:
        - Contacts
      operationId: deleteContact
      summary: Deletes a particular contact from Voluble
      security:
        - jwt: []
      responses:
        "200":
          description: Contact deleted successfully
        "400":
          $ref: "#/components/responses/400"
        "404":
          $ref: "#/components/responses/404"
        "410":
          $ref: "#/components/responses/410"
        "500":
          $ref: "#/components/responses/500"
  /orgs/{org-id}/messages:
    parameters:
      - $ref: "#/components/parameters/org-id"
    get:
      tags:
        - Messages
      description: >-
        Returns a list of the first 100 Messages available to the User, starting
        at `offset`
      summary: Returns a list of the first 100 Messages available to the User
      security:
        - jwt: []
      parameters:
        - name: offset
          in: query
          required: false
          schema:
            type: integer
            default: 0
            minimum: 0
            format: int64
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Message"
                maxItems: 100
        "500":
          $ref: "#/components/responses/500"
    post:
      tags:
        - Messages
      summary: Creates and sends a new Message
      security:
        - jwt: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Message"
      responses:
        "201":
          description: >-
            Message attempt successfully created; the created Message will be
            returned
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Message"
          links:
            GetMessageById:
              operationId: getMessage
              parameters:
                contact_id: "$response.body#/id"
        "400":
          $ref: "#/components/responses/400"
        "500":
          $ref: "#/components/responses/500"
  /orgs/{org-id}/messages/{message_id}:
    parameters:
      - $ref: "#/components/parameters/org-id"
      - name: message_id
        description: The UUID of the Message within Voluble to manipulate
        required: true
        in: path
        schema:
          type: string
    get:
      tags:
        - Messages
      operationId: getMessage
      summary: Retrieves a specific Message
      security:
        - jwt: []
      responses:
        "200":
          description: Message retrieved successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Message"
        "404":
          $ref: "#/components/responses/404"
        "500":
          $ref: "#/components/responses/500"
  /services:
    get:
      tags:
        - Services
      summary: >-
        Returns a list of all of the Services available to the User in the
        Organization
      description: >-
        Returns a list of all of the Services available to the User in the
        Organization
      security:
        - jwt: []
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Service"
                maxItems: 100
        "500":
          $ref: "#/components/responses/500"
  /services/{service_id}:
    parameters:
      - name: service_id
        description: The UUID of the Service within Voluble to manipulate
        required: true
        in: path
        schema:
          type: string
    get:
      tags:
        - Services
      summary: Retrieves a specified Service
      security:
        - jwt: []
      responses:
        "200":
          description: Retrieved service OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Service"
        "404":
          $ref: "#/components/responses/404"
        "500":
          $ref: "#/components/responses/500"
  /orgs/{org-id}/servicechains:
    parameters:
      - $ref: "#/components/parameters/org-id"
    get:
      tags:
        - Servicechains
      summary: >-
        Returns a list of all of the Servicechains available to the User in the
        Organization
      description: >-
        Returns a list of all of the Servicechains available to the User in the
        Organization
      security:
        - jwt: []
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Servicechain"
                maxItems: 100
        "500":
          $ref: "#/components/responses/500"
    post:
      tags:
        - Servicechains
      summary: Creates a new Servicechain
      security:
        - jwt: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Servicechain"
      responses:
        "201":
          description: Servicechain created successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Servicechain"
        "400":
          $ref: "#/components/responses/400"
        "500":
          $ref: "#/components/responses/500"
  /orgs/{org-id}/servicechains/{servicechain_id}:
    parameters:
      - $ref: "#/components/parameters/org-id"
      - name: servicechain_id
        description: The UUID of the Servicechain within Voluble to manipulate
        required: true
        in: path
        schema:
          type: string
    get:
      tags:
        - Servicechains
      security:
        - jwt: []
      summary: Retrieves the Servicechain with the specified ID
      responses:
        "200":
          description: Servicechain retrieved successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Servicechain"
        "404":
          $ref: "#/components/responses/404"
        "500":
          $ref: "#/components/responses/500"
    put:
      tags:
        - Servicechains
      security:
        - jwt: []
      summary: Modifies the Servicechain with the specified ID
      requestBody:
        required: true
        description: The new data to replace the specified parameters with
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Servicechain"
      responses:
        "200":
          description: Servicechain modified successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Servicechain"
        "400":
          $ref: "#/components/responses/400"
        "404":
          $ref: "#/components/responses/404"
        "500":
          $ref: "#/components/responses/500"
    delete:
      tags:
        - Servicechains
      security:
        - jwt: []
      summary: Removes the Servicechain with the specified ID
      responses:
        "200":
          description: Servicechain deleted successfully
        "400":
          $ref: "#/components/responses/400"
        "404":
          $ref: "#/components/responses/404"
        "410":
          $ref: "#/components/responses/410"
        "500":
          $ref: "#/components/responses/500"
  /orgs:
    get:
      tags:
        - Organizations
      summary: Returns a list of all of the Organizations available
      description: Returns a list of all of the Organizations available
      security:
        - jwt: []
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Organization"
                maxItems: 100
        "500":
          $ref: "#/components/responses/500"
    post:
      tags:
        - Organizations
      summary: Creates a new Organizations
      security:
        - jwt: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Organization"
      responses:
        "201":
          description: Organization created successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Organization"
        "400":
          $ref: "#/components/responses/400"
        "500":
          $ref: "#/components/responses/500"
  /orgs/{org-id}:
    parameters:
      - $ref: "#/components/parameters/org-id"
    get:
      tags:
        - Organizations
      security:
        - jwt: []
      summary: Retrieves the Organization with the specified ID
      responses:
        "200":
          description: Organization retrieved successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Organization"
        "404":
          $ref: "#/components/responses/404"
        "500":
          $ref: "#/components/responses/500"
    put:
      tags:
        - Organizations
      security:
        - jwt: []
      summary: Modifies the Organization with the specified ID
      requestBody:
        required: true
        description: The new data to replace the specified parameters with
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Organization"
      responses:
        "200":
          description: Organization modified successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Organization"
        "400":
          $ref: "#/components/responses/400"
        "404":
          $ref: "#/components/responses/404"
        "500":
          $ref: "#/components/responses/500"
    delete:
      tags:
        - Organizations
      security:
        - jwt: []
      summary: Removes the Organization with the specified ID
      responses:
        "200":
          description: Organization deleted successfully
        "400":
          $ref: "#/components/responses/400"
        "404":
          $ref: "#/components/responses/404"
        "410":
          $ref: "#/components/responses/410"
        "500":
          $ref: "#/components/responses/500"