openapi: 3.0.1
info:
  title: Brand Registration API
  version: 0.0.1-beta4
  description: |
    Vodafone Brand Registration API allows clients to register their brand information along with optional antispoofing feature to Vodafone Branded Calling platform. 
    The API can be exposed to clients directly or through an aggregator platform. 
    Brand Registration API facilitates enrichment of calls in the network as to display the name of the caller to the called party and optionally request an antispoofing check.

servers:
  - url: https://api-sandbox.vf-dmp.engineering.vodafone.com/brandregistration/v1
    description: "Sandbox"
  - url: https://api.vf-dmp.engineering.vodafone.com/brandregistration/v1
    description: "Production"

tags:
  - name: Create Branded Calling Information
    description: |
       Register new brand information to Vodafone Branded Calling platform
  - name: Update Branded Calling Information
    description: |
       Update existing brand registration in Vodafone Branded Calling platform
  - name: Delete Branded Calling Information
    description: |
       Delete existing brand registration from Vodafone Branded Calling platform  
  - name: Query Branded Calling Information
    description: |
       Query existing brand registration in Vodafone Branded Calling platform

paths:
  /registrations :
    post:
      tags:
        - Create Branded Calling Information
      x-openapi-router-controller: app.controllers.admins_controller
      summary: Register new brand information in Branded Calling platform
      description: Register new brand information along with optional antispoofing feature request to Vodafone Branded Calling platform.
      operationId: create_registration_by_number
      parameters:
        - $ref: '#/components/parameters/XVfCorrelationIdParam'
        # - $ref: '#/components/parameters/XVfPartnerId'
      requestBody:
        required: true
        description: Object to represent parameters of a registration request
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/createOrUpdateRecordRequest"

      responses:
        "201":
          $ref: '#/components/responses/201Created'
        '400':
          $ref: '#/components/responses/Generic400'
        '401':
          $ref: '#/components/responses/Generic401'
        '403':
          $ref: '#/components/responses/Generic403'
        '404':
          $ref: '#/components/responses/Generic404'
        '405':
          $ref: '#/components/responses/Generic405'
        '406':
          $ref: '#/components/responses/Generic406'
        '409':
          $ref: '#/components/responses/Generic409'
        '415':
          $ref: '#/components/responses/Generic415'
        '429':
          $ref: '#/components/responses/Generic429'
        '500':
          $ref: '#/components/responses/Generic500'
        '502':
          $ref: '#/components/responses/Generic502'
        '503':
          $ref: '#/components/responses/Generic503'
        '504':
          $ref: '#/components/responses/Generic504'


      security:
        - oAuthSample:
          - BRAND_REGISTRATION_APIGEE_PRODUCT
  
  /registrations/{registrationId}:  
    put:
      tags:
        - Update Branded Calling Information
      x-openapi-router-controller: app.controllers.admins_controller
      summary: Update existing brand registration in Branded Calling platform
      description: Update existing brand registration in Vodafone Branded Calling platform.
      operationId: update_registration_by_id
      parameters:
        - $ref: '#/components/parameters/XVfCorrelationIdParam'
        # - $ref: '#/components/parameters/XVfPartnerId'
        - description: Unique identifier of an existing brand registration
          in: path
          name: registrationId
          required: true
          example: "9e765f76-8037-4e5f-ba5d-e0c87c09a320"
          schema:
            type: string
      requestBody:
        required: true
        description: Request body with the brand registration identifier that was received after a successful brand creation (POST) request
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/createOrUpdateRecordRequest"
      responses:
        "204":
          $ref: '#/components/responses/204NoContent'
        '400':
          $ref: '#/components/responses/Generic400'
        '401':
          $ref: '#/components/responses/Generic401'
        '403':
          $ref: '#/components/responses/Generic403'
        '404':
          $ref: '#/components/responses/Generic404'
        '405':
          $ref: '#/components/responses/Generic405'
        '406':
          $ref: '#/components/responses/Generic406'
        '409':
          $ref: '#/components/responses/Generic409'
        '415':
          $ref: '#/components/responses/Generic415'
        '429':
          $ref: '#/components/responses/Generic429'
        '500':
          $ref: '#/components/responses/Generic500'
        '502':
          $ref: '#/components/responses/Generic502'
        '503':
          $ref: '#/components/responses/Generic503'
        '504':
          $ref: '#/components/responses/Generic504'
       
      security:
        - oAuthSample:
          - BRAND_REGISTRATION_APIGEE_PRODUCT
    delete:
      tags:
        - Delete Branded Calling Information
      x-openapi-router-controller: app.controllers.admins_controller
      summary: Delete existing brand registration from Branded Calling platform
      description: Delete existing brand registration from Vodafone Branded Calling platform
      operationId: delete_registration_by_id
      parameters:
        - $ref: '#/components/parameters/XVfCorrelationIdParam'
        # - $ref: '#/components/parameters/XVfPartnerId'
        - description: Unique identifier of an existing brand registration
          in: path
          name: registrationId
          required: true
          example: "9e765f76-8037-4e5f-ba5d-e0c87c09a320"
          schema:
            type: string
      responses:
        "204":
          $ref: '#/components/responses/204NoContent'
        '400':
          $ref: '#/components/responses/Generic400'
        '401':
          $ref: '#/components/responses/Generic401'
        '403':
          $ref: '#/components/responses/Generic403'
        '404':
          $ref: '#/components/responses/Generic404'
        '405':
          $ref: '#/components/responses/Generic405'
        '406':
          $ref: '#/components/responses/Generic406'
        '415':
          $ref: '#/components/responses/Generic415'
        '429':
          $ref: '#/components/responses/Generic429'
        '500':
          $ref: '#/components/responses/Generic500'
        '502':
          $ref: '#/components/responses/Generic502'
        '503':
          $ref: '#/components/responses/Generic503'
        '504':
          $ref: '#/components/responses/Generic504'
       
      security:
        - oAuthSample:
          - BRAND_REGISTRATION_APIGEE_PRODUCT

    get:
      tags:
        - Query Branded Calling Information
      x-openapi-router-controller: app.controllers.admins_controller
      summary: Read an existing brand registration from Branded Calling platform
      description: Read an existing brand registration from Vodafone Branded Calling platform
      operationId: get_registration_by_id
      parameters:
        - $ref: '#/components/parameters/XVfCorrelationIdParam'
        # - $ref: '#/components/parameters/XVfPartnerId'
        - description: Unique identifier of an existing brand registration
          in: path
          name: registrationId
          required: true
          example: "9e765f76-8037-4e5f-ba5d-e0c87c09a320"
          schema:
            type: string
      responses:
        "200":
          $ref: '#/components/responses/200Record'
        '400':
          $ref: '#/components/responses/Generic400'
        '401':
          $ref: '#/components/responses/Generic401'
        '403':
          $ref: '#/components/responses/Generic403'
        '404':
          $ref: '#/components/responses/Generic404'
        '405':
          $ref: '#/components/responses/Generic405'
        '406':
          $ref: '#/components/responses/Generic406'
        '415':
          $ref: '#/components/responses/Generic415'
        '429':
          $ref: '#/components/responses/Generic429'
        '500':
          $ref: '#/components/responses/Generic500'
        '502':
          $ref: '#/components/responses/Generic502'
        '503':
          $ref: '#/components/responses/Generic503'
        '504':
          $ref: '#/components/responses/Generic504'
       
      security:
        - oAuthSample:
          - BRAND_REGISTRATION_APIGEE_PRODUCT

  /ping:
    get:
      tags:
        - Monitoring
      summary: Check the upstream system is up and running.
      description: |-
        This API is to check the upstream system is up and running.

      security:
        - oAuthSample: []

      operationId: getPing

      parameters:
        - $ref: "#/components/parameters/XVfCorrelationIdParam"

      responses:
        "200":
          description: "**OK**"
          content:
            application/json:
              examples:
                success_response:
                  value: {
                            "suffix": "/ping",
                            "client": "35.191.13.203",
                            "startTime": "2023-06-05T19:47:16.794Z",
                            "endTime": "2023-06-05T19:47:16.888Z",
                            "responseTime": 94,
                            "message": "PONG"
                          }
        '400':
          $ref: '#/components/responses/Generic400'
        '401':
          $ref: '#/components/responses/Generic401'
        '403':
          $ref: '#/components/responses/Generic403'
        '404':
          $ref: '#/components/responses/Generic404'
        '405':
          $ref: '#/components/responses/Generic405'
        '406':
          $ref: '#/components/responses/Generic406'
        '415':
          $ref: '#/components/responses/Generic415'
        '429':
          $ref: '#/components/responses/Generic429'
        '500':
          $ref: '#/components/responses/Generic500'
        '502':
          $ref: '#/components/responses/Generic502'
        '503':
          $ref: '#/components/responses/Generic503'
        '504':
          $ref: '#/components/responses/Generic504'

  /status:
    get:
      tags:
        - Monitoring
      summary: Check the downstream system is up and running.
      description: |-
        This API is to check the downstream system is up and running.

      security:
        - oAuthSample: []

      operationId: getStatus

      parameters:
        - $ref: "#/components/parameters/XVfCorrelationIdParam"

      responses:
        "200":
          description: "**OK**"
          content:
            application/json:
              examples:
                success_response:
                  value: {
                            "status": "OK",

                          }
        '400':
          $ref: '#/components/responses/Generic400'
        '401':
          $ref: '#/components/responses/Generic401'
        '403':
          $ref: '#/components/responses/Generic403'
        '404':
          $ref: '#/components/responses/Generic404'
        '405':
          $ref: '#/components/responses/Generic405'
        '406':
          $ref: '#/components/responses/Generic406'
        '415':
          $ref: '#/components/responses/Generic415'
        '429':
          $ref: '#/components/responses/Generic429'
        '500':
          $ref: '#/components/responses/Generic500'
        '502':
          $ref: '#/components/responses/Generic502'
        '503':
          $ref: '#/components/responses/Generic503'
        '504':
          $ref: '#/components/responses/Generic504'
          
components:
  securitySchemes:
    oAuthSample:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: '/oauth2/v1/token'
          scopes:
            BRAND_REGISTRATION_APIGEE_PRODUCT: API Consumer is allowed to consume the Branded Call Registration API

  responses:
    201Created:
      description: Registration created successfully
      headers:
        Cache-Control:
          $ref: '#/components/headers/Cache-Control'
        Strict-Transport-Security:
          $ref: '#/components/headers/Strict-Transport-Security'
        Date:
          $ref: '#/components/headers/Date'
        X-Content-Type-Options:
          $ref: '#/components/headers/X-Content-Type-Options'
        Content-Type:
          $ref: '#/components/headers/Content-Type'
        X-Correlator:
          $ref: '#/components/headers/X-Correlator'
        Server:
          $ref: '#/components/headers/Server'
      content:
        application/json:
          schema:
              $ref: '#/components/schemas/createRecordResponse'
    200Record:
      description: Registration read successfully
      headers:
        Cache-Control:
          $ref: '#/components/headers/Cache-Control'
        Strict-Transport-Security:
          $ref: '#/components/headers/Strict-Transport-Security'
        Date:
          $ref: '#/components/headers/Date'
        X-Content-Type-Options:
          $ref: '#/components/headers/X-Content-Type-Options'
        Content-Type:
          $ref: '#/components/headers/Content-Type'
        X-Correlator:
          $ref: '#/components/headers/X-Correlator'
        Server:
          $ref: '#/components/headers/Server'
      content:
        application/json:
          schema:
              $ref: '#/components/schemas/readRecordResponse'              
    204NoContent:
      description: Successful response with no content
      headers:
        Cache-Control:
          $ref: '#/components/headers/Cache-Control'
        Strict-Transport-Security:
          $ref: '#/components/headers/Strict-Transport-Security'
        Date:
          $ref: '#/components/headers/Date'
        X-Content-Type-Options:
          $ref: '#/components/headers/X-Content-Type-Options'
        # Content-Type:
        #   $ref: '#/components/headers/Content-Type'
        X-Correlator:
          $ref: '#/components/headers/X-Correlator'
        Server:
          $ref: '#/components/headers/Server'
   
   ############## Added Camara Error Structure ###########################################
   
    Generic400:
      description: |
        **Bad Request**
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          examples:
            invalid argument:
              value:
                status: 400
                code: INVALID_ARGUMENT
                message: Client specified an invalid argument, request body or query param
    Generic401:
      description: |
        **Unauthorized**
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          examples:
            invalid creds:
              value:
                status: 401
                code: UNAUTHENTICATED
                message: Request not authenticated due to missing, invalid, or expired credentials
    Generic403:
      description: |
        **Forbidden**
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          examples:
            permission denied:
              value:
                status: 403
                code: PERMISSION_DENIED
                message: Client does not have sufficient permissions to perform this action
    Generic404:
      description: |
        **Not Found**
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          examples:

              NOT_FOUND:
                value: {
                          "status": 404,
                          "code" : "NOT_FOUND",
                          "message": "The specified resource is not found."
                        }
              UNKNOWN_PHONE_NUMBER:
                value: {
                          "status": 404,
                          "code" : "UNKNOWN_PHONE_NUMBER",
                          "message": "Can't be checked because the phone number is unknown."
                        }
    Generic405:
      description: |
        **Method Not Allowed**
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          examples:
            METHOD_NOT_ALLOWED:
              value:
                status: 405
                code: METHOD_NOT_ALLOWED
                message: The requested method is not allowed/supported on
                      the target resource"
    Generic406:
      description: |
        **Not Acceptable**
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          examples:
            Not Acceptable:
              value:
                status: 406
                code: Not Acceptable
                message: The server cannot produce a response matching
                          the content requested by the client through Accept-* headers."
                          
    Generic409:
      description: |
        **Conflict**
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          examples:

              CONFLICT:
                value: {
                          "status": 409,
                          "code" : "CONFLICT",
                          "message": "The specified resource duplicate entry found."
                        }
              ALREADY_EXISTS:
                value: {
                          "status": 404,
                          "code" : "ALREADY_EXISTS",
                          "message": "The specified resource that client tried to create already exists."
                        }
    Generic415:
      description: |
        **Unsupported Media Type**
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          examples:
            UNSUPPORTED_MEDIA_TYPE:
              value:
                status: 415
                code: UNSUPPORTED_MEDIA_TYPE
                message: The server refuses to accept the request because
                      the payload format is in an unsupported format
                      
    Generic429:
      description: |
        **Too Many Requests**
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          examples:
              SpikeArrestViolation:
                value: {
                          "status": 429,
                          "code" : "TOO_MANY_REQUESTS",
                          "message": "Spike Arrest Violation."
                        }
              QuotaViolation:
                value: {
                          "status": 429,
                          "code" : "TOO_MANY_REQUESTS",
                          "message": "API/App/Country Quota limit reached."
                        }
                        
    Generic500:
      description: |
        **Internal Server Error**
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          examples:
            Internal_Server_Error:
              value:
                status: 500
                code: INTERNAL
                message: The server encountered an unexpected condition
                      that prevented it from fulfilling the request
    Generic502:
      description: |
        **Bad Gateway**
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          examples:
            Bad_Gateway:
              value:
                status: 502
                code: BAD_GATEWAY
                message: An upstream internal service cannot be reached

    Generic503:
      description: |
        **UNAVAILABLE**
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          examples:
            UNAVAILABLE:
              value:
                status: 503
                code: UNAVAILABLE
                message: Request timeout exceeded
    Generic504:
      description: |
        **Gateway Timeout**
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          examples:
            TIMEOUT:
              value:
                status: 504
                code: TIMEOUT
                message: Request timeout exceeded. 
            
   
   
####################################################################################################################   
   
   
   
   
   
   


  schemas:
    registrationId:
      type: string
      format: uuid
      description: Unique identifier of a registration created in the Branded Calling Platform as a result of the POST operation.
      example: "9e765f76-8037-4e5f-ba5d-e0c87c09a320"

    phoneNumber:
      type: string
      pattern: '^\+[1-9][0-9]{4,14}$|^\+[1-9][0-9]{4,13}\*$'
      description: E.164 Format international telephone number prefixed with '+' representing the calling party. Service provider may support trailing wildcard character '*'.
      example: "+441234567890"
    
    phoneNumberAlternate:
      type: string
      pattern: '^\+[1-9][0-9]{4,14}$|^\+[1-9][0-9]{4,13}\*$'
      description: Indicates FROM field when different from p-asserted-Identity. Service provider may support trailing wildcard character '*'
      example: "+441234567891"
    
    clientId:
      type: string
      description: Unique customer identifier for a brand
      example: "VODA"
    
    displayName:
      type: string
      maxLength: 32
      description: Brand information that will be displayed for the calling party
      example: "Vodafone Call Center"

    verifyCallerAction:
      type: string
      description: >-
        Indicates if Antispoofing feature is enabled for the A-party, if enabled what action to take in case antispoofing check fails
      example: "DO_NOT_BRAND"
      enum:
        - "DO_NOT_VERIFY"
        - "BLOCK_UNVERIFIED"
        - "DO_NOT_BRAND"
    
    terminatingCountryCode:
      type: integer
      description: Country Code of the called number in E.164 format
      example: 44  

    campaign:
      type: string
      description: Logical name to group PhoneNumbers belonging to a Brand
      example: "Vodafone Promotions"

    createOrUpdateRecordRequest:
      type: object
      description: "Request object to create or update (replace) an registration in the Branded Calling platform"
      required:
        - "phoneNumber"
        - "displayName"
        - "terminatingCountryCode"
      properties:
        phoneNumber:
          $ref: '#/components/schemas/phoneNumber'
        phoneNumberAlternate:
          $ref: '#/components/schemas/phoneNumberAlternate'
        displayName:
          $ref: '#/components/schemas/displayName'
        clientId:
          $ref: '#/components/schemas/clientId'          
        verifyCallerAction:
          $ref: '#/components/schemas/verifyCallerAction'
        terminatingCountryCode:
          $ref: '#/components/schemas/terminatingCountryCode'
        campaign:
          $ref: '#/components/schemas/campaign'

    readRecordResponse:
      type: object
      description: "Object to represent a single registration in the Branded Calling platform"
      required:
        - "registrationId"
        - "phoneNumber"
        - "displayName"
        - "terminatingCountryCode"
        
      properties:
        registrationId:
          $ref: '#/components/schemas/registrationId'
        phoneNumber:
          $ref: '#/components/schemas/phoneNumber'
        phoneNumberAlternate:
          $ref: '#/components/schemas/phoneNumberAlternate'
        displayName:
          $ref: '#/components/schemas/displayName'
        clientId:
          $ref: '#/components/schemas/clientId'
        verifyCallerAction:
          $ref: '#/components/schemas/verifyCallerAction'
        terminatingCountryCode:
          $ref: '#/components/schemas/terminatingCountryCode'
        campaign:
          $ref: '#/components/schemas/campaign'

    createRecordResponse:
      type: object
      description: "Object returned upon successful registration"
      required: 
        - "registrationId"
      properties:
        registrationId:
          $ref: '#/components/schemas/registrationId'
          
############################# Add Camara Schema ###############################################################

    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


  
  parameters:
    XVfCorrelationIdParam:
      name: X-Correlator
      in: header
      description:
        This will be used as an unique transactionid and correlation to be used between response and the corresponding request
      required: false
      example: "9e765f76-8037-4e5f-ba5d-e0c87c09a320"
      schema:
        type: string
        format: uuid

    XVfPartnerId:
      name: partnerId
      in: header
      description:
        Unique reference associated to an onboarded partner
      required: true
      example: "VIH001"
      schema:
        type: string

  headers:
    Cache-Control:
      schema:
        type: string
        default: "no-store,no-cache"
      description: >
        used to specify browser caching policies in both client requests and server responses

    Strict-Transport-Security:
      schema:
        type: string
        default: "max-age=15724800;includeSubDomains"
      description: >
        web security policy mechanism which helps to protect websites against protocol downgrade attacks and cookie hijacking
    Date:
      schema:
        type: string
        format: date-time
      description: >
        Time the server constructed the response. example: e.g. YYY-MM-DDThh:mm:ssZ

    X-Content-Type-Options: 
      schema:
        type: string
        default: "nosniff"
      description: >
        prevent the browser from interpreting files as a different MIME type to what is specified in the Content-Type HTTP header

    Content-Type:
      schema:
        type: string
        default: application/json
      description: >
            The Content-Type entity header is used to indicate the media type of the resource.

    X-Correlator:
      schema:
        type: string
        format: uuid
      description: >
            The Correlation ID that will be used to allow correlation between response and corresponding request
    Server:
      schema:
        type: string
        default: VF
      description: Identification of the responding server