CAMARA Project Call Forwarding information retrieval API

openapi: 3.2.0
info:
  title: Call Forwarding Signal Call Forwarding information…
  description: '# Overview

    The Call Forwarding Signal API provides the API Consumer with

    information about the status of the Call Forwarding Service on a specific

    phone number.'
  version: wip
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
  x-camara-commonalities: 0.6
servers:
- url: '{apiRoot}/call-forwarding-signal/vwip'
  variables:
    apiRoot:
      default: http://localhost:9091
      description: API root, defined by the service provider, e.g. `api.example.com` or `api.example.com/somepath`
tags:
- name: Call Forwarding Information Retrieval
  description: Provides information on Call Forwarding settings for the provided phone number (PhoneNumber).
paths:
  /call-forwardings:
    post:
      tags:
      - Call Forwarding Information Retrieval
      security:
      - openId:
        - call-forwarding-signal:call-forwardings:read
      summary: Retrieve the information about the type of call forwarding service active on a…
      description: This endpoint provides information about which type of call forwarding service is active. More than one service can be active, e.g. conditional and unconditional. This endpoint exceeds the main scope of the Call Forwarding Signal API, for this reason an error code 501 can be returned.
      operationId: retrieveCallForwarding
      parameters:
      - $ref: '#/components/parameters/x-correlator'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCallForwardingSignal'
        required: true
      responses:
        '200':
          description: OK.
          headers:
            x-correlator:
              $ref: '#/components/headers/x-correlator'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CallForwardingSignal'
        '400':
          $ref: '#/components/responses/Generic400'
        '404':
          $ref: '#/components/responses/Generic404'
        '401':
          $ref: '#/components/responses/Generic401'
        '403':
          $ref: '#/components/responses/Generic403'
        '422':
          $ref: '#/components/responses/Generic422'
        '429':
          $ref: '#/components/responses/Generic429'
        '501':
          $ref: '#/components/responses/Generic501'
components:
  responses:
    Generic404:
      description: Not found
      headers:
        x-correlator:
          $ref: '#/components/headers/x-correlator'
      content:
        application/json:
          schema:
            allOf:
            - $ref: '#/components/schemas/ErrorInfo'
            - type: object
              properties:
                status:
                  enum:
                  - 404
                code:
                  enum:
                  - NOT_FOUND
                  - IDENTIFIER_NOT_FOUND
          examples:
            GENERIC_404_NOT_FOUND:
              description: Resource is not found
              value:
                status: 404
                code: NOT_FOUND
                message: The specified resource is not found.
            GENERIC_404_IDENTIFIER_NOT_FOUND:
              description: Call forwarding check can't be done because the phone number is unknown.
              value:
                status: 404
                code: IDENTIFIER_NOT_FOUND
                message: Device identifier not found.
    Generic422:
      description: Unprocessable Content
      headers:
        x-correlator:
          $ref: '#/components/headers/x-correlator'
      content:
        application/json:
          schema:
            allOf:
            - $ref: '#/components/schemas/ErrorInfo'
            - type: object
              properties:
                status:
                  enum:
                  - 422
                code:
                  enum:
                  - SERVICE_NOT_APPLICABLE
                  - MISSING_IDENTIFIER
                  - UNNECESSARY_IDENTIFIER
          examples:
            GENERIC_422_SERVICE_NOT_APPLICABLE:
              description: Service not applicable for the provided identifier
              value:
                status: 422
                code: SERVICE_NOT_APPLICABLE
                message: The service is not available for the provided identifier.
            GENERIC_422_MISSING_IDENTIFIER:
              description: An identifier is not included in the request and the device or phone number identification cannot be derived from the 3-legged access token
              value:
                status: 422
                code: MISSING_IDENTIFIER
                message: The phone number cannot be identified.
            GENERIC_422_UNNECESSARY_IDENTIFIER:
              description: An explicit identifier is provided when a device or phone number has already been identified from the access token
              value:
                status: 422
                code: UNNECESSARY_IDENTIFIER
                message: The phone number is already identified by the access token.
    Generic400:
      description: Bad Request
      headers:
        x-correlator:
          $ref: '#/components/headers/x-correlator'
      content:
        application/json:
          schema:
            allOf:
            - $ref: '#/components/schemas/ErrorInfo'
            - type: object
              properties:
                status:
                  enum:
                  - 400
                code:
                  enum:
                  - INVALID_ARGUMENT
          examples:
            GENERIC_400_INVALID_ARGUMENT:
              description: Invalid Argument. Generic Syntax Exception
              value:
                status: 400
                code: INVALID_ARGUMENT
                message: Client specified an invalid argument, request body or query param.
    Generic401:
      description: Unauthorized
      headers:
        x-correlator:
          $ref: '#/components/headers/x-correlator'
      content:
        application/json:
          schema:
            allOf:
            - $ref: '#/components/schemas/ErrorInfo'
            - type: object
              properties:
                status:
                  enum:
                  - 401
                code:
                  enum:
                  - UNAUTHENTICATED
          examples:
            GENERIC_401_UNAUTHENTICATED:
              description: Request cannot be authenticated and a new authentication is required
              value:
                status: 401
                code: UNAUTHENTICATED
                message: Request not authenticated due to missing, invalid, or expired credentials. A new authentication is required.
    Generic501:
      description: Not Implemented
      headers:
        x-correlator:
          $ref: '#/components/headers/x-correlator'
      content:
        application/json:
          schema:
            allOf:
            - $ref: '#/components/schemas/ErrorInfo'
            - type: object
              properties:
                status:
                  enum:
                  - 501
                code:
                  enum:
                  - NOT_IMPLEMENTED
          examples:
            GENERIC_501_NOT_IMPLEMENTED:
              description: Service not implemented. The use of this code should be avoided as far as possible to get the objective to reach aligned implementations
              value:
                status: 501
                code: NOT_IMPLEMENTED
                message: This functionality is not implemented yet.
    Generic429:
      description: Too Many Requests
      headers:
        x-correlator:
          $ref: '#/components/headers/x-correlator'
      content:
        application/json:
          schema:
            allOf:
            - $ref: '#/components/schemas/ErrorInfo'
            - type: object
              properties:
                status:
                  enum:
                  - 429
                code:
                  enum:
                  - QUOTA_EXCEEDED
                  - TOO_MANY_REQUESTS
          examples:
            GENERIC_429_QUOTA_EXCEEDED:
              description: Request is rejected due to exceeding a business quota limit
              value:
                status: 429
                code: QUOTA_EXCEEDED
                message: Out of resource quota.
            GENERIC_429_TOO_MANY_REQUESTS:
              description: Access to the API has been temporarily blocked due to rate or spike arrest limits being reached
              value:
                status: 429
                code: TOO_MANY_REQUESTS
                message: Rate limit reached.
    Generic403:
      description: Forbidden
      headers:
        x-correlator:
          $ref: '#/components/headers/x-correlator'
      content:
        application/json:
          schema:
            allOf:
            - $ref: '#/components/schemas/ErrorInfo'
            - type: object
              properties:
                status:
                  enum:
                  - 403
                code:
                  enum:
                  - PERMISSION_DENIED
          examples:
            GENERIC_403_PERMISSION_DENIED:
              description: Permission denied. OAuth2 token access does not have the required scope or when the user fails operational security
              value:
                status: 403
                code: PERMISSION_DENIED
                message: Client does not have sufficient permissions to perform this action.
  schemas:
    PhoneNumber:
      description: A public identifier addressing a telephone subscription. In mobile networks it corresponds to the MSISDN (Mobile Station International Subscriber Directory Number). In order to be globally unique it has to be formatted in international format, according to E.164 standard, prefixed with '+'.
      type: string
      pattern: ^\+[1-9][0-9]{4,14}$
      example: '+123456789'
    ErrorInfo:
      type: object
      required:
      - status
      - code
      - message
      properties:
        status:
          type: integer
          description: HTTP response status code
        code:
          type: string
          description: A human-readable code to describe the error
        message:
          type: string
          description: A human-readable description of what the event represents
    CallForwardingSignal:
      description: resource containing the list of the Call Forwarding Services active for the given phone number (PhoneNumber). The possible states are, 'inactive' (no call forwarding service activated), 'unconditional' (call forwarded independently from the device status), 'conditional_busy' (call forwarded if the device is on an active call), 'conditional_not_reachable' (call forwarded if the device is not reachable), 'conditional_no_answer' (call forwarded if the device doesn't answer the incoming call).
      type: array
      items:
        type: string
        enum:
        - inactive
        - unconditional
        - conditional_busy
        - conditional_not_reachable
        - conditional_no_answer
      example:
      - unconditional
      - conditional_busy
      - conditional_no_answer
      minItems: 1
    CreateCallForwardingSignal:
      description: resource containing the phone number (PhoneNumber) regarding which the Call Forwarding Service must be checked. To be provided/valued only in case of two-legged authentication. If provided/valued with three-legged authentication a 422-UNNECESSARY_IDENTIFIER error code is returned.
      type: object
      properties:
        phoneNumber:
          $ref: '#/components/schemas/PhoneNumber'
    XCorrelator:
      type: string
      pattern: ^[a-zA-Z0-9-_:;.\/<>{}]{0,256}$
      example: b4333c46-49c0-4f62-80d7-f0ef930f1c46
  parameters:
    x-correlator:
      name: x-correlator
      in: header
      description: Correlation id for the different services
      schema:
        $ref: '#/components/schemas/XCorrelator'
  headers:
    x-correlator:
      description: Correlation id for the different services
      schema:
        $ref: '#/components/schemas/XCorrelator'
  securitySchemes:
    openId:
      description: to support Consent Management
      type: openIdConnect
      openIdConnectUrl: https://example.com/.well-known/openid-configuration
externalDocs:
  description: Product documentation at CAMARA
  url: https://github.com/camaraproject/CallForwardingSignal