Enkudo_DSP_Subscription.yaml

openapi: '3.0.0'
info:
  title: 'Enkudo DSP Northbound Subscription API'
  description: |
    Enkudo DSP is Telenity’s next-generation digital services platform to monetize the 
    digital services and content served on top of the customer network. Enkudo DSP solution 
    enables customers to subscribe/purchase digital content of their choice (ranging from 
    games, video stream, educational content, etc.) through a mobile application and web 
    portal with a variety of payment options, on a revenue share business model.
    This API is for the consumption of Content Providers. It provides end-user subscription, 
    unsubscription, query information and notification interfaces for DSP. 
    <br><br>
    NGSSM's subscription API is inbound, meaning that, for this API, NGSSM acts as the server
    and request direction is from the client to NGSSM. Subscription APIs include  methods: 
    - Generate Authcode, 
    - ReGenerate Authcode, 
    - Create Subscription and 
    - Cancel Subscription
    - Query Subscriber Info 

    As the names imply, Authcode methods are used to create a one-time password token at OTPS, 
    Create Subscription is used to create an offer subscription at NGSSM, 
    whereas Cancel Subscription is used to cancel an existing offer subscription on NGSSM
  version: '1.0'
servers:
  - url: 'http://localhost:8080/v1/subscription'
    description: Development server
  - url: 'https://api.enkudo-{customer}.com/v1/subscription'
    description: Production server
    variables:
      customer:
        default: demo
        description: Enkudo customer name
  - url: 'https://api-test.enkudo-{customer}.com/v1/subscription'
    description: Test server
    variables:
      customer:
        default: demo
        description: Enkudo customer name.
paths:
  /authcode:
    post:
      operationId: getAuthCode
      summary : Authorization Code Request
      description: |
        'Before issuing any requests to the endpoint, web applications need to be authenticated. 
        For authentication, Client Credentials grant of OAuth 2.0 specification is used. 
        Please refer to  for more information on OAuth.http://tools.ietf.org/html/rfc6749#section-4.4
        The client authentication follows these steps:
        - Client encodes its key and password into an encoded set of credentials.
        - Client makes a request to OAuth/token?grant_type=client_credentials endpoint and 
          passes the credentials information in the POST request.
        - If successfully authenticated, client receives an access token in the response.
        - Client includes this bearer token when making requests to the DCB API'
      security:
        - BarerAuth: []
      requestBody:
        $ref: '#/components/requestBodies/AuthCodeRequestBody'
        required: true
      responses:
        '200':
          description: 'Successful Authorization Code Request'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthCodeRsp'
        '403':
          $ref: 'Enkudo_DSP_CommonData.yaml#/components/responses/403'
        '404': 
          $ref: 'Enkudo_DSP_CommonData.yaml#/components/responses/404'
        '500':
          $ref: 'Enkudo_DSP_CommonData.yaml#/components/responses/500'
  /authcode/{trxid}:
    put:
      operationId: regenerateAuthCode
      summary: Regenerate Auth-Code
      description: | 
        'Regenerate Auth Code API has the same basic functionality of Generate API with one caveat: 
        It first invalidates the current Auth Code and only then generates a new random password 
        and sends it to the application. The created is password is not sent to the subscriber.
        The application can send the password to the subscriber by any means it prefers.
        For Regenerate Auth Code API to be called successfully, Generate Auth Code must have been 
        called first and there should be a valid Transaction ID from that API call'
      security:
        - BarerAuth: []
      parameters: 
        - name: trxid
          in: path
          schema:
            $ref: 'Enkudo_DSP_CommonData.yaml#/components/schemas/trxid'
          required: true
      responses:
        '200':
          description: 'Successful Authorization Code Request'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegenerateAuthCodeRsp'
        '403':
          $ref: 'Enkudo_DSP_CommonData.yaml#/components/responses/403'
        '404': 
          $ref: 'Enkudo_DSP_CommonData.yaml#/components/responses/404'
        '500':
          $ref: 'Enkudo_DSP_CommonData.yaml#/components/responses/500'
  /subscribe:
    post:
      operationId: subscribe
      summary: Create Subscription
      description: 'Subscribes the customer identified with the parameters passed in the JSON body parameter "offer"'
      security:
        - BearerAuth: []
      parameters:
        - in: header 
          name: authCode
          description: '>>>>>Authorization code receveid be get/regenerateAuthCode'
          schema:
           $ref: 'Enkudo_DSP_CommonData.yaml#/components/schemas/trxid'
        - in: header
          name: trxid
          description: '>>>>>>Authorization code receveid be get/regenerateAuthCode'
          schema:
            $ref: 'Enkudo_DSP_CommonData.yaml#/components/schemas/trxid'
        - in: header
          name: RequestedServiceId
          description: 'id of requested service to subscribe'
          schema:
            $ref: 'Enkudo_DSP_CommonData.yaml#/components/schemas/serviceId' 
      requestBody:
        $ref: '#/components/requestBodies/SubscribeRequestBody'
        required: true
      responses:
        '200':
          description: 'Successfully subscribed to the requested content'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscribeRsp'
        '403':
          $ref: 'Enkudo_DSP_CommonData.yaml#/components/responses/403'
        '404': 
          $ref: 'Enkudo_DSP_CommonData.yaml#/components/responses/404'
        '500':
          $ref: 'Enkudo_DSP_CommonData.yaml#/components/responses/500'     
        default:
          $ref: 'Enkudo_DSP_CommonData.yaml#/components/responses/default'     
  
      callbacks:
        onSubscriptionStateChangeEvent:
          '{$request.body#/subStateChangeNotificationUri}':
            post:
              parameters:
                - name: Content-Encoding
                  in: header
                  description: Content-Encoding, described in IETF RFC 7231
                  schema:
                    type: string
              requestBody:
                  $ref: '#/components/requestBodies/NotificationBody'
              responses:
                '200':
                  description: Expected response to a successful notification processing
                '403':
                  $ref: 'Enkudo_DSP_CommonData.yaml#/components/responses/403'
                '404': 
                  $ref: 'Enkudo_DSP_CommonData.yaml#/components/responses/404'
                '500':
                  $ref: 'Enkudo_DSP_CommonData.yaml#/components/responses/500'
                default:
                  $ref: 'Enkudo_DSP_CommonData.yaml#/components/responses/default'   



  /unsubscribe:
    put:
      operationId: unsubscribe
      description: |
        'Cancels the existing subscription of the customer identified with the parameters passed 
        in the JSON body parameter offer'
      security:
        - BearerAuth: []
      parameters:
        - in: header 
          name: RequestedServiceId
          description: 'id of requested service to subscribe'
          schema:
            type: string
      requestBody:
        $ref: '#/components/requestBodies/UnsubscribeRequestBody'
        required: true

      responses:
        '200':
          description: 'Successfully unsubscribed from the given content'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnsubscribeRsp'
        '403':
          $ref: 'Enkudo_DSP_CommonData.yaml#/components/responses/403'
        '404': 
          $ref: 'Enkudo_DSP_CommonData.yaml#/components/responses/404'
        '500':
          $ref: 'Enkudo_DSP_CommonData.yaml#/components/responses/500'
        default:
          $ref: 'Enkudo_DSP_CommonData.yaml#/components/responses/default'   
  /query/{msisdn}:
    get:
      operationId: getMSISDN
      description: |
        'Query the subscriptions of the customer identified with the msisdn passed in the URL.'
      security:
        - BearerAuth: []
      parameters:
        - name: msisdn
          in: path
          required: true
          schema:
            $ref: 'Enkudo_DSP_CommonData.yaml#/components/schemas/msisdn' 
      responses:
        '200':
          description: 'Successfully retrived subscriber info'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueryRsp'
        '403':
          $ref: 'Enkudo_DSP_CommonData.yaml#/components/responses/403'
        '404': 
          $ref: 'Enkudo_DSP_CommonData.yaml#/components/responses/404'
        '500':
          $ref: 'Enkudo_DSP_CommonData.yaml#/components/responses/500'
        default:
          $ref: 'Enkudo_DSP_CommonData.yaml#/components/responses/default'   
components:
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic
    BearerAuth:
      type: http
      scheme: bearer
  schemas:
    AuthCodeRsp:
      type: object
      properties:
        trxid:
          $ref: 'Enkudo_DSP_CommonData.yaml#/components/schemas/trxid'
      required:
        - trxid
    Subscription:
      type: object
      properties:
        services:
          description: 'List of the subscribed service unique names and IDs.'
          type: array
          items: 
            $ref: 'Enkudo_DSP_CommonData.yaml#/components/schemas/service'
            maxItems: 64
        offer:
          description: 'The unique name of an offer that is subscribed by the MSISDN'
          type: string 
          maxLength: 64
        price:
          description: 'The main price for the offer. Only applicable for NGSSM Service Offers'
          type: integer
          format: int32
        startDate:
          description: 'The first subscription start date'
          type: string
          format: date-time
        state:
          description: |
            'The new state of service subscription. It can have the following values;
            - ACTIVE = 3rd party application should provide service to subscriber.
            - SUSPENDED = In case of charging failures, subscription is suspended. 3rd party
            applications should notprovide service.
            - INACTIVE = When subscription is finished, subscription state is changed
            to INACTIVE. 3rd party application should not provide service to subscriber.
            - INPROGRESS = This state indicates that subscription related operations are taking
            place. 3rd party application should not provide service to subscriber.
            - PENDING = This state indicates that consent is asked to subscriber and the
            response is expected. 
            
            3rd party application should not provide service to subscriber.
            3rd Party should provide service to subscriber only when state is ACTIVE. 
            On all other cases, subscriber should not be served by 3rd party application.
          enum:
            - active
            - suspended
            - inactive 
            - inprogress 
            - pending
      required:
        - services
        - startDate
        - state

    RegenerateAuthCodeRsp:
      type: object
      properties:
        otp:
          description: 'Generated OTP, empty, not shared withthe Client'
          type: string
          maxLength: 256
        trxid:
          $ref: 'Enkudo_DSP_CommonData.yaml#/components/schemas/trxid' 
        type:
          description: 'Type of the generated Auth Code'
          $ref: 'Enkudo_DSP_CommonData.yaml#/components/schemas/type' 
        length: 
          description: 'Generated OTP length'
          type: integer
          format: int32
        channel:
          $ref: 'Enkudo_DSP_CommonData.yaml#/components/schemas/channel' 
        template:
          description: 'Generated OTP SMS template. Always"default"'
          type: string
          default: 'default'
        validityPeriodInSeconds:
          description: 'OTP validity period in seconds'
          type: integer
          format: int32
        createdAt:
          description: 'OTP creation time in miliseconds from Unix epoch(?) in local time'
          type: integer
          format: int64
        expiresAt:
          description: 'OTP expiry time in miliseconds from Unix epoch(?) in local time'
          type: integer
          format: int64
        maxVerificationAttempts:
          description: |
            'Maximum number of attempts allowed for OTP verification to the Client 
            (and so the customer).'
          type: integer
          format: int32
        remainingVerificationAttempts:
          description: |
            'Remaining number of attempts allowed for OTP verification to the Client 
            (and so the customer).'
          type: integer
          format: int32
        maxRegenerationAttempts:
          description: |
            'Maximum number of attempts allowed for OTP regeneration to the Client 
            (and so thecustomer)'
          type: integer
          format: int32
        remainingRegenerationAttempts:
          description: |
            'Remaining number of attempts allowed for OTP regeneration to the Client 
            (and so thecustomer)'
          type: integer
          format: int32
        minRegenerationDelayInSeconds:
          description: |
            'Minimum delay in seconds before the Client can trigger OTP renegeneration'
          type: integer
          format: int32
      required:
        - otp
        - trxid
        - type
        - length
        - channel
        - template
        - validityPeriodInSeconds
        - createdAt
        - expiresAt
        - maxVerificationAttempts
        - remainingRegenerationAttempts
        - minRegenerationDelayInSeconds
    SubscribeRsp:
      type: object
      properties:
        subscriptionId:
          $ref: 'Enkudo_DSP_CommonData.yaml#/components/schemas/subscriptionId'
      required:
        - subscriptionId
    UnsubscribeRsp:
      type: object
      properties:
        subscriptionId:
          $ref: 'Enkudo_DSP_CommonData.yaml#/components/schemas/subscriptionId'
      required:
        - subscriptionId
 
    QueryRsp:
      type: object
      properties:
        subscriptions:
          type: array
          items: 
            $ref: '#/components/schemas/Subscription'
          maxItems: 64
      required:
        - subscriptions
 
  requestBodies:
    AuthCodeRequestBody:
      description: ''
      required: true
      content:
        application/json:
          schema:
            $ref: 'Enkudo_DSP_CommonData.yaml#/components/schemas/AuthCodeRequestBody'
    SubscribeRequestBody:
      description: ''
      required: true
      content:
        application/json:
          schema:
            $ref: 'Enkudo_DSP_CommonData.yaml#/components/schemas/SubscribeRequestBody'
    UnsubscribeRequestBody:
      description: ''
      required: true
      content:
        application/json:
          schema:
            $ref: 'Enkudo_DSP_CommonData.yaml#/components/schemas/UnsubscribeRequestBody'

    NotificationBody:
      description: 'Notification Payload'
      required: true
      content:
        application/json:
          schema:
            $ref: 'Enkudo_DSP_CommonData.yaml#/components/schemas/NotificationBody'