openapi: 3.0.3
info:
  title: Global System for Mobile Communications GSMA Camara Project SMS API
  description: "SMS API provides the customer with the ability to send an SMS to a mobile phone number in use on a mobile phone device. There are 3 different categories of SMS, namely Service SMS, Promotional SMS and Transactional SMS.  The SMS API can also be used to send a binary message to a mobile phone number which is being used on an (IoT) device.\v "
  version: 0.1.0-alpha.1
  termsOfService: http://example.com/terms/
  contact:
    name: API Support
    url: http://www.example.com/support
    email: support@example.com
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
externalDocs:
  description: Product documentation at Camara
  url: https://github.com/camaraproject/ShortMessageService
servers:
  - url: '{apiRoot}/{basePath}'
    variables:
      apiRoot:
        default: http://localhost:9091
        description: API root
      basePath:
        default: sms/v0alpha1
        description: Base path for the Short Message Service
tags:
  - name: Send SMS
paths:
  /short-message:
    post:
      security:
        - openId:
            - send-sms:short-message
      tags:
        - Send SMS
      summary: Global System for Mobile Communications Send SMS
      description: >
        The customer application server makes a request to the SMS API to send
        SMS message to the destination address.
      operationId: send-sms
      parameters:
        - $ref: '#/components/parameters/x-correlator'
      requestBody:
        description: |
          Submit a request for sending SMS to the destination address
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MessageRequest'
            examples:
              MessageRequest:
                value:
                  to:
                    - '+910123456789'
                  from: '+919876543210'
                  category: PROMOTION
                  message: xxxxxxxxxx
        required: true
      responses:
        '200':
          $ref: '#/components/responses/Generic200'
        '400':
          $ref: '#/components/responses/Generic400'
        '401':
          $ref: '#/components/responses/Generic401'
        '403':
          $ref: '#/components/responses/Generic403'
        '404':
          $ref: '#/components/responses/Generic404'
        '500':
          $ref: '#/components/responses/Generic500'
        '503':
          $ref: '#/components/responses/Generic503'
components:
  securitySchemes:
    openId:
      type: openIdConnect
      openIdConnectUrl: https://example.com/.well-known/openid-configuration
  parameters:
    x-correlator:
      name: x-correlator
      in: header
      description: Correlation id for the different services
      schema:
        type: string
  headers:
    x-correlator:
      description: Correlation id for the different services
      schema:
        type: string
  schemas:
    MessageRequest:
      type: object
      required:
        - to
        - from
        - message
      properties:
        to:
          type: array
          description: The recipients MSISDN
          items:
            type: string
        from:
          type: string
          description: The senders MSISDN
        category:
          type: string
          enum:
            - PROMOTION
            - SERVICE
            - TRANSACTION
        message:
          type: string
          description: SMS message
    MessageResponse:
      type: object
      required:
        - msgId
        - timestamp
      properties:
        msgId:
          type: string
          description: >-
            The SMS messages sent to the recipients are identified by smsnumber
            are identified.
        timestamp:
          type: string
          format: date-time
          description: >-
            Timestamp when SMS was delivered. It must follow [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) and
            must have time zone. Recommended format is
            yyyy-MM-dd'T'HH:mm:ss.SSSZ (i.e. which allows
            2023-07-03T14:27:08.312+02:00 or 2023-07-03T12:27:08.312Z)
    ErrorInfo:
      type: object
      required:
        - status
        - code
        - detail
      properties:
        status:
          type: integer
          description: HTTP response status code
        code:
          type: string
          description: Code given to this error
        detail:
          type: string
          description: Detailed error description
  responses:
    Generic200:
      description: OK
      headers:
        x-correlator:
          description: Correlation id for the different services
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/MessageResponse'
          example:
            msgId: 56647d96-b3e6-48d2-b93f-ab0d56bdd965
            timestamp: '2024-03-19T12:33:27.070Z'
    Generic400:
      description: Problem with the client request
      headers:
        x-correlator:
          description: Correlation id for the different services
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          example:
            status: 400
            code: INVALID_ARGUMENT
            detail: Client specified an invalid argument, request body or query param
    Generic401:
      description: Authentication problem with the client request
      headers:
        x-correlator:
          description: Correlation id for the different services
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          example:
            status: 401
            code: UNAUTHENTICATED
            detail: >-
              Request not authenticated due to missing, invalid, or expired
              credentials
    Generic403:
      description: Client does not have sufficient permission
      headers:
        x-correlator:
          description: Correlation id for the different services
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          examples:
            PermissionDenied:
              value:
                status: 403
                code: PERMISSION_DENIED
                detail: >-
                  Client does not have sufficient permissions to perform this
                  action
            InvalidTokenContext:
              value:
                status: 403
                code: INVALID_TOKEN_CONTEXT
                detail: Phone number cannot be deducted from access token context
    Generic404:
      description: Resource Not Found
      headers:
        x-correlator:
          description: Correlation id for the different services
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          example:
            status: 404
            code: NOT_FOUND
            detail: A specified resource is not found
    Generic500:
      description: Server error
      headers:
        x-correlator:
          description: Correlation id for the different services
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          example:
            status: 500
            code: INTERNAL
            detail: Server error
    Generic503:
      description: Service unavailable. Typically the server is down.
      headers:
        x-correlator:
          description: Correlation id for the different services
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          example:
            status: 503
            code: UNAVAILABLE
            detail: Service unavailable