Global System for Mobile Communications SMS Delivery Notification Subscription API

openapi: 3.2.0
info:
  title: Global System for Mobile Communications GSMA Camara Project Endpoint Discovery Application SMS Delivery Notification Subscription API
  version: 0.1.0-wip
  description: The Application Discovery API extends beyond the capabilities of the Simple Edge Discovery API by not only locating the nearest Edge Cloud Zone but also directly linking to the application endpoints within those Edge Cloud Zones.
  contact:
    email: sp-edc@lists.camaraproject.org
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
servers:
- url: '{apiRoot}/{basePath}'
  variables:
    apiRoot:
      default: https://localhost:443
      description: API root.
    basePath:
      default: application-endpoint-discovery/vwip
      description: Base path for the Application Endpoint Discovery.
tags:
- name: SMS Delivery Notification Subscription
  description: Operation to manage event subscription on sms delivery event (swapped)
paths:
  /subscriptions:
    post:
      tags:
      - SMS Delivery Notification Subscription
      summary: Global System for Mobile Communications Create a sms delivery event subscription for a given consumer
      description: Create a sms delivery event subscription for a given consumer
      operationId: createSMSDeliverySubscription
      parameters:
      - $ref: '#/components/parameters/x-correlator'
      security:
      - openId:
        - sms-delivery:subscriptions:create
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSubscription'
        required: true
      callbacks:
        notifications:
          '{$request.body#/webhook/notificationUrl}':
            post:
              tags:
              - Session notifications callback
              summary: Session notifications callback
              description: 'Important: this endpoint is to be implemented by the API consumer.

                The sim swap server will call this endpoint whenever a swapped event occurs.

                '
              operationId: postNotification
              parameters:
              - $ref: '#/components/parameters/x-correlator'
              requestBody:
                required: true
                content:
                  application/json:
                    schema:
                      $ref: '#/components/schemas/CloudEvent'
                    examples:
                      STATUS:
                        $ref: '#/components/examples/STATUS'
                      SUBSCRIPTION_ENDS:
                        $ref: '#/components/examples/SUBSCRIPTION_ENDS'
              responses:
                '204':
                  description: Successful notification
                  headers:
                    x-correlator:
                      $ref: '#/components/headers/x-correlator'
                '400':
                  $ref: '#/components/responses/Generic400'
                '401':
                  $ref: '#/components/responses/Generic401'
                '403':
                  $ref: '#/components/responses/Generic403'
                '500':
                  $ref: '#/components/responses/Generic500'
                '503':
                  $ref: '#/components/responses/Generic503'
              security:
              - {}
              - notificationsBearerAuth: []
      responses:
        '201':
          description: Created
          headers:
            x-correlator:
              $ref: '#/components/headers/x-correlator'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionInfo'
        '202':
          description: Request accepted to be processed. It applies for async creation process.
          headers:
            x-correlator:
              $ref: '#/components/headers/x-correlator'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionAsync'
        '400':
          $ref: '#/components/responses/Generic400'
        '401':
          $ref: '#/components/responses/Generic401'
        '403':
          $ref: '#/components/responses/Generic403'
        '409':
          $ref: '#/components/responses/Generic409'
        '500':
          $ref: '#/components/responses/Generic500'
        '503':
          $ref: '#/components/responses/Generic503'
    get:
      tags:
      - SMS Delivery Notification Subscription
      summary: Global System for Mobile Communications Retrieve a list of SMS Delivery event subscription
      description: Retrieve a list of SMS Delivery event subscription(s)
      operationId: retrieveSubscriptionList
      parameters:
      - $ref: '#/components/parameters/x-correlator'
      security:
      - openId:
        - sim-swap:subscriptions:read
      responses:
        '200':
          description: List of event subscription details
          headers:
            x-correlator:
              $ref: '#/components/headers/x-correlator'
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SubscriptionInfo'
        '400':
          $ref: '#/components/responses/Generic400'
        '401':
          $ref: '#/components/responses/Generic401'
        '403':
          $ref: '#/components/responses/Generic403'
        '500':
          $ref: '#/components/responses/Generic500'
        '503':
          $ref: '#/components/responses/Generic503'
  /subscriptions/{subscriptionId}:
    get:
      tags:
      - SMS Delivery Notification Subscription
      summary: Global System for Mobile Communications Retrieve a sms delivery event subscription for a phone number
      description: retrieve event subscription information for a given subscription.
      operationId: retrieveSubscription
      security:
      - openId:
        - sim-swap:subscriptions:read
      parameters:
      - $ref: '#/components/parameters/SubscriptionId'
      - $ref: '#/components/parameters/x-correlator'
      responses:
        '200':
          description: OK
          headers:
            x-correlator:
              $ref: '#/components/headers/x-correlator'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionInfo'
        '400':
          $ref: '#/components/responses/SubscriptionIdRequired'
        '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'
    delete:
      tags:
      - SMS Delivery Notification Subscription
      summary: Global System for Mobile Communications Delete a sms delivery event subscription
      operationId: deleteSubscription
      description: delete a given event subscription.
      security:
      - openId:
        - sim-swap:subscriptions:delete
      parameters:
      - $ref: '#/components/parameters/SubscriptionId'
      - $ref: '#/components/parameters/x-correlator'
      responses:
        '202':
          description: Request accepted to be processed. It applies for async deletion process.
          headers:
            x-correlator:
              $ref: '#/components/headers/x-correlator'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionAsync'
        '204':
          description: event subscription deleted
          headers:
            x-correlator:
              $ref: '#/components/headers/x-correlator'
        '400':
          $ref: '#/components/responses/SubscriptionIdRequired'
        '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:
  schemas:
    DateTime:
      type: string
      format: date-time
      description: Timestamp of when the occurrence happened. Must adhere to RFC 3339.
      example: '2018-04-05T17:31:00Z'
    ErrorInfo:
      type: object
      required:
      - status
      - code
      - message
      properties:
        status:
          type: integer
          description: HTTP response status code
        code:
          type: string
          description: Code given to this error
        message:
          type: string
          description: Detailed error description
    CreateSubscription:
      description: The request for creating a sim swap event subscription
      type: object
      required:
      - webhook
      - subscriptionDetail
      properties:
        subscriptionDetail:
          $ref: '#/components/schemas/SubscriptionDetail'
        subscriptionExpireTime:
          type: string
          format: date-time
          example: '2023-01-17T13:18:23.682Z'
          description: The subscription expiration time in date-time format.
        subscriptionMaxEvents:
          type: integer
          description: Identifies the maximum number of event reports to be generated (>=1) - Once this number is reached, the subscription ends. -1 means there is no limit.
          example: -1
        webhook:
          $ref: '#/components/schemas/Webhook'
    SubscriptionAsync:
      description: Response for a sim swap operation managed asynchronously (Creation or Deletion)
      type: object
      properties:
        subscriptionId:
          $ref: '#/components/schemas/SubscriptionId'
    SubscriptionDetail:
      type: object
      description: The detail of the requested event subscription
      required:
      - senderId
      - type
      properties:
        senderId:
          $ref: '#/components/schemas/SenderId'
        type:
          $ref: '#/components/schemas/SmsDeliveryNotificationEventType'
    CloudEvent:
      description: The notification callback
      required:
      - id
      - source
      - specversion
      - type
      - data
      properties:
        id:
          type: string
          description: identifier of this event, that must be unique in the source context.
        source:
          $ref: '#/components/schemas/Source'
        type:
          $ref: '#/components/schemas/SmsDeliveryNotificationEventType'
        specversion:
          type: string
          description: Version of the specification to which this event conforms (must be 1.0 if it conforms to cloudevents 1.0.2 version)
          example: 1
        datacontenttype:
          type: string
          description: media-type that describes the event payload encoding, must be "application/json" for CAMARA APIs
          example: application/json
        data:
          type: object
          description: Event details payload described in each CAMARA API and referenced by its type
        time:
          $ref: '#/components/schemas/DateTime'
      discriminator:
        propertyName: type
        mapping:
          org.camaraproject.sms.v0.sms-delivery-status: '#/components/schemas/EventSimSwap'
          org.camaraproject.sms.v0.subscription-ends: '#/components/schemas/EventSimSwapSubscriptionEnds'
    SenderId:
      type: string
      description: Identifer for the matching criteria basis which call back would be triggered by the server. In this case it would be the message sender id.
      example: AD-HDFCBK
    SubscriptionInfo:
      description: Represents a sim swaps subscription.
      required:
      - startsAt
      - subscriptionId
      allOf:
      - $ref: '#/components/schemas/CreateSubscription'
      - type: object
        properties:
          subscriptionId:
            $ref: '#/components/schemas/SubscriptionId'
          subscriptionDetail:
            $ref: '#/components/schemas/SubscriptionDetail'
          subscriptionExpireTime:
            type: string
            format: date-time
            example: '2023-01-17T13:18:23.682Z'
            description: The subscription expiration time in date-time format.
          webhook:
            $ref: '#/components/schemas/Webhook'
          startsAt:
            type: string
            format: date-time
            description: date time when subscription started
          expiresAt:
            type: string
            format: date-time
            description: date time when subscription will expire or expired
        required:
        - eventSubscriptionId
        - type
    Webhook:
      description: Webhook information for event channel
      type: object
      required:
      - notificationUrl
      properties:
        notificationUrl:
          type: string
          example: https://application-server.com
          description: https callback address where the event notification must be POST-ed
        notificationAuthToken:
          type: string
          example: c8974e592c2fa383d4a3960714
          description: 'OAuth2 token to be used by the callback API endpoint. It MUST be indicated within HTTP Authorization header e.g. Authorization: Bearer $notificationAuthToken

            '
    SmsDeliveryNotificationEventType:
      type: string
      description: 'sms-delivery - Event triggered after sms-delivery task is complete. This sms-delivery tasks completion may have status/outcome as success or failure which is returned back in callback to the requestor.

        '
      enum:
      - org.camaraproject.sms.v0.sms-delivery-status
    Source:
      type: string
      format: uri-reference
      minLength: 1
      description: Identifies the context in which an event happened in the specific Provider Implementation.
      example:
      - https://github.com/cloudevents
      - mailto:cncf-wg-serverless@lists.cncf.io
      - urn:uuid:6e8bc430-9c3a-11d9-9669-0800200c9a66
      - cloudevents/spec/pull/123
      - /sensors/tn-1234567/alerts
      - 1-555-123-4567
    SubscriptionId:
      type: string
      description: The event subscription identifier.
      example: qs15-h556-rt89-1298
  responses:
    Generic403:
      description: Client does not have sufficient permission
      headers:
        x-correlator:
          $ref: '#/components/headers/x-correlator'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          example:
            status: 403
            code: PERMISSION_DENIED
            message: Client does not have sufficient permissions to perform this action
    Generic404:
      description: Resource Not Found
      headers:
        x-correlator:
          $ref: '#/components/headers/x-correlator'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          example:
            status: 404
            code: NOT_FOUND
            message: The specified resource is not found
    Generic401:
      description: Authentication problem with the client request
      headers:
        x-correlator:
          $ref: '#/components/headers/x-correlator'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          example:
            status: 401
            code: UNAUTHENTICATED
            message: Request not authenticated due to missing, invalid, or expired credentials
    SubscriptionIdRequired:
      description: Problem with the client request
      headers:
        x-correlator:
          $ref: '#/components/headers/x-correlator'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          examples:
            Generic400:
              summary: Schema validation failed
              value:
                status: 400
                code: INVALID_ARGUMENT
                message: Client specified an invalid argument, request body or query param
            subscriptionIdRequired:
              summary: subscription id is required
              value:
                status: 400
                code: INVALID_ARGUMENT
                message: 'Expected property is missing: subscriptionId'
    Generic409:
      description: Conflict
      headers:
        x-correlator:
          $ref: '#/components/headers/x-correlator'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          example:
            status: 409
            code: CONFLICT
            message: The specified resource is in a conflict
    Generic500:
      description: Server error
      headers:
        x-correlator:
          $ref: '#/components/headers/x-correlator'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          example:
            status: 500
            code: INTERNAL
            message: Server error
    Generic503:
      description: Service unavailable. Typically the server is down.
      headers:
        x-correlator:
          $ref: '#/components/headers/x-correlator'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          example:
            status: 503
            code: UNAVAILABLE
            message: Service unavailable
    Generic400:
      description: Problem with the client request
      headers:
        x-correlator:
          $ref: '#/components/headers/x-correlator'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          example:
            status: 400
            code: INVALID_ARGUMENT
            message: Client specified an invalid argument, request body or query param
  examples:
    SUBSCRIPTION_ENDS:
      value:
        id: 123658
        source: supertelco.notificationSendServer12
        type: org.camaraproject.sim-swap.v0.subscription-ends
        specversion: '1.0'
        datacontenttype: application/json
        data:
          phoneNumber: 123456789
          terminationReason: SUBSCRIPTION_EXPIRED
          subscriptionId: 2ghy-55gg-7iup-yuo9
          terminationDescription: subscription expire time reached
        time: '2023-01-19T13:18:23.682Z'
    STATUS:
      value:
        id: 123655
        source: supertelco.notificationSendServer12
        type: org.camaraproject.sms.v0.sms-delivery-status
        specversion: '1.0'
        datacontenttype: application/json
        data:
          msgId: 56647d96-b3e6-48d2-b93f-ab0d56bdd965
          subscriptionId: 2ghy-55gg-7iup-yuo9
        time: '2023-01-18T13:18:23.682Z'
  parameters:
    SubscriptionId:
      name: subscriptionId
      in: path
      description: Subscription identifier that was obtained from the create event subscription operation
      required: true
      schema:
        $ref: '#/components/schemas/SubscriptionId'
    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
  securitySchemes:
    openId:
      description: OpenID Provider Configuration Information.
      type: openIdConnect
      openIdConnectUrl: .well-known/openid-configuration
externalDocs:
  description: Product documentation at CAMARA.
  url: https://github.com/camaraproject/EdgeCloud