openapi.yaml

openapi: 3.0.3

info:
  title: Messages dispatcher
  version: 1.0.0
  description: Service which acts as dispatcher for messages to end-users through 3rd-party application
  contact:
    name: Antonio Tarricone
    email: antonio.tarricone@pagopa.it

servers:
  - description: Development Test
    url: https://api-io.dev.cstar.pagopa.it/emd/message-core
    x-internal: true
  - description: User Acceptance Test
    url: https://api-io.uat.cstar.pagopa.it/emd/message-core
    x-internal: true
tags:
  - name: submit
    description: Related to 'submit' operations

security:
  - bearerAuth: [ ]

paths:
  /sendMessage:
    parameters:
      - $ref: '#/components/parameters/RequestId'

    post:
      operationId: submitMessage
      description: Submit a message
      tags: [ submit ]
      requestBody:
        $ref: '#/components/requestBodies/SendMessage'
      responses:
        "200":
          #description: No channels enabled
          $ref: '#/components/responses/SendMessageNoChannelsEnabled'
        "202":
          #description: Accepted
          $ref: '#/components/responses/SendMessageOk'
        "400":
          #description: Bad request
          $ref: '#/components/responses/Error'
        "401":
          #description: Access token is missing or invalid
          $ref: '#/components/responses/Error'
        "403":
          #description: Forbidden
          $ref: '#/components/responses/Error'
        "406":
          #description: Not acceptable. Did you require application/json?
          $ref: '#/components/responses/Error'
        "415":
          #description: Unsupported media type. Did you provide application/json?
          $ref: '#/components/responses/Error'
        "429":
          #description: Too many requests
          $ref: '#/components/responses/Error'
        "500":
          #description: Server error
          $ref: '#/components/responses/Error'
        default:
          description: Unexpected error

components:
  schemas:
    AccessControlAllowOrigin:
      description: Indicates whether the response can be shared with requesting code from the given origin
      type: string
      pattern: "^[ -~]{1,2048}$"
      minLength: 1
      maxLength: 2048

    Error:
      description: Error details
      type: object
      additionalProperties: false
      properties:
        code:
          $ref: '#/components/schemas/ErrorCode'
        description:
          $ref: '#/components/schemas/ErrorDescription'
      required:
        - code
        - description
      example:
        code: "001000001"
        description: "Generic error"

    ErrorCode:
      description: Error code
      type: string
      pattern: "^[A-F0-9]{9}$"
      minLength: 9
      maxLength: 9
      example: "001000001"

    ErrorDescription:
      description: Error description
      type: string
      pattern: "^[ -~]{1,256}$"
      minLength: 1
      maxLength: 256
      example: "Unexpected error from server"

    Errors:
      description: List of errors
      type: object
      additionalProperties: false
      properties:
        errors:
          type: array
          minItems: 1
          maxItems: 32
          items:
            $ref: '#/components/schemas/Error'
      required:
        - errors
      example:
        errors:
          - code: "00000000A"
            description: "Generic error"
          - code: "001000001"
            description: "Unexpected error from server"

    OutcomeOk:
      description: Outcome of submit operation
      type: string
      enum:
        - OK
      example: "OK"

    OutcomeNoChannelsEnabled:
      description: Outcome of submit operation
      type: string
      enum:
        - NO_CHANNELS_ENABLED
      example: "NO_CHANNELS_ENABLED"

    RateLimitLimit:
      description: The number of allowed requests in the current period
      type: integer
      format: int32
      minimum: 1
      maximum: 240

    RateLimitReset:
      description: The number of seconds left in the current period
      type: integer
      format: int32
      minimum: 1
      maximum: 60

    RetryAfter:
      description: The number of seconds to wait before allowing a follow-up request
      type: integer
      format: int32
      minimum: 1
      maximum: 240

    SendMessageRequest:
      type: object
      properties:
        messageId:
          description: Unique ID of the message
          type: string
          pattern: "^[ -~]{24,64}$"
          minLength: 24
          maxLength: 64
        recipientId:
          description: ID of the recipient
          type: string
          pattern: "^[ -~]{8,64}$"
          minLength: 8
          maxLength: 64
        triggerDateTime:
          description: When (date and time) the subject who originated the message requested to send it
          type: string
          format: date-time
          minLength: 19
          maxLength: 19
        senderDescription:
          description: Description of the subject who originated the message
          type: string
          pattern: "^[ -~]{1,50}$"
          minLength: 1
          maxLength: 50
        authenticationType:
          description: Type of authentication
          type: string
          enum:
            - OAUTH2
        authenticationUrl:
          description: URL to retrieve access_token
          type: string
          format: uri
          pattern: "^[ -~]{1,2048}$"
          minLength: 1
          maxLength: 2048
        messageUrl:
          description: URL to retrieve the original message
          type: string
          format: uri
          pattern: "^[ -~]{1,2048}$"
          minLength: 1
          maxLength: 2048
        originId:
          description: ID of the original message
          type: string
          pattern: "^[ -~]{24,36}$"
          minLength: 24
          maxLength: 36
        message:
          description: Content of the message
          type: string
          pattern: "^[ -~]{1,140}$"
          minLength: 1
          maxLength: 140
      required:
        - messageId
        - recipientId
        - message
        - authenticationType
      example:
        messageId: "8a32fa8a-5036-4b39-8f2e-47d3a6d23f9e"
        recipientId: "RSSMRA85T10A562S"
        message: "You have a ticket!"
        authenticationType: "OAUTH2"

    UUID:
      description: UUID
      type: string
      pattern: "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$"
      minLength: 36
      maxLength: 36
      example: "d0d654e6-97da-4848-b568-99fedccb642b"

  requestBodies:
    SendMessage:
      description: Request to send a message
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SendMessageRequest'

  parameters:
    RequestId:
      name: RequestId
      in: header
      description: Request ID that will be logged by the service
      required: true
      schema:
        $ref: '#/components/schemas/UUID'

  responses:
    Error:
      description: Error response
      headers:
        Access-Control-Allow-Origin:
          description: Indicates whether the response can be shared with requesting code from the given origin
          required: false
          schema:
            $ref: '#/components/schemas/AccessControlAllowOrigin'
        RateLimit-Limit:
          description: The number of allowed requests in the current period
          required: false
          schema:
            $ref: '#/components/schemas/RateLimitLimit'
        RateLimit-Reset:
          description: The number of seconds left in the current period
          required: false
          schema:
            $ref: '#/components/schemas/RateLimitReset'
        Retry-After:
          description: The number of seconds to wait before allowing a follow-up request
          required: false
          schema:
            $ref: '#/components/schemas/RetryAfter'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Errors'

    SendMessageOk:
      description: Response to send message request when it is accepted
      headers:
        Access-Control-Allow-Origin:
          description: Indicates whether the response can be shared with requesting code from the given origin
          required: false
          schema:
            $ref: '#/components/schemas/AccessControlAllowOrigin'
        RateLimit-Limit:
          description: The number of allowed requests in the current period
          required: false
          schema:
            $ref: '#/components/schemas/RateLimitLimit'
        RateLimit-Reset:
          description: The number of seconds left in the current period
          required: false
          schema:
            $ref: '#/components/schemas/RateLimitReset'
        Retry-After:
          description: The number of seconds to wait before allowing a follow-up request
          required: false
          schema:
            $ref: '#/components/schemas/RetryAfter'
      content:
        application/json:
          schema:
            type: object
            properties:
              outcome:
                $ref: '#/components/schemas/OutcomeOk'

    SendMessageNoChannelsEnabled:
      description: Response to send message request when no channels are enabled
      headers:
        Access-Control-Allow-Origin:
          description: Indicates whether the response can be shared with requesting code from the given origin
          required: false
          schema:
            $ref: '#/components/schemas/AccessControlAllowOrigin'
        RateLimit-Limit:
          description: The number of allowed requests in the current period
          required: false
          schema:
            $ref: '#/components/schemas/RateLimitLimit'
        RateLimit-Reset:
          description: The number of seconds left in the current period
          required: false
          schema:
            $ref: '#/components/schemas/RateLimitReset'
        Retry-After:
          description: The number of seconds to wait before allowing a follow-up request
          required: false
          schema:
            $ref: '#/components/schemas/RetryAfter'
      content:
        application/json:
          schema:
            type: object
            properties:
              outcome:
                $ref: '#/components/schemas/OutcomeNoChannelsEnabled'

  securitySchemes:
    bearerAuth:
      description: A bearer token in the format of a JWS and conforms to the specifications included in RFC8725
      type: http
      scheme: bearer
      bearerFormat: JWT