test

code/API_definitions/Traffic Influence/Call_Forwarding_Signal.yaml

@@ -0,0 +1,306 @@
+openapi: 3.0.3
+############################################################################
+#                                     API info                             #
+############################################################################
+info:
+  title: Call Forwarding Signal API
+  version: 0.1.3-wip
+  description: |
+    ## Overview
+    The Call Forwarding Signal (CFS) API provides the API Consumer with an
+    information about the status of the Call Forwading Service on a specific
+    phone number.
+    ## 1. Introduction
+    The Call Forwarding Service is provided by the Network to a phone number.
+    Thi service redirects the incoming call to that phone number to an
+    alternative destination such a another phone number or a voice mail system.\
+    The CFS API can be invoked to get the status of the Call Forwarding Service
+    for a specific phone number.
+    ## 2. Quick Start
+    The CFS API is a REST API based on the CreateCallForwardingSignal resource. 
+    This resource is filled during the API invokation, by the API Consumer, 
+    with the phone number on which the Call Forwardging Service status must be
+    verified.
+    A responce is provided by the API Producer with an resource, CallForwordings
+    , containing a boolean with the status beeing active or not.\
+    \
+    Before starting to use the Call Forwarding API, the developer needs to know
+    about the below specified details:\
+    \
+    **Base-Url**
+    The RESTful CFS API endpoint, for example
+    [**https://tim-api.developer.tim.it/callforwardingsignal**](https://tim-api\
+    .developer.tim.it/callforwarding\signal)\
+    \
+    **PhoneNumber**
+    This is the end user phone number. The CFS API verifies if a call forwarding
+    service is active on this phone number.\
+    \
+    **CreateCallForwordingSignal**
+    This is the resource the API Consumer uses to define the phone number to \
+    be verified about the status of the Network Call Forarding service.\
+    \
+    **CallForwordingSignal**
+    This is the resource the API Producer provides back to the API Consumer.\
+    This Resource contains the status of the Network Call Forarding service for\
+    the specified phone number.
+    ## 3. Authorization and authentication
+    CAMARA guidelines defines a set of authorization flows which can grant API 
+    clients access to the API functionality,
+    as outlined in the document [CAMARA-API-access-and-user-consent.md](https:\
+    //github.com/camaraproject/IdentityAndConsentManagement/blob/main/\
+    documentation/CAMARA-API-access-and-user-consent.md).
+    Which specific authorization flows are to be used will be determined during
+    onboarding process, happening between the API Client and the
+    Telco Operator exposing the API, taking into account the declared purpose
+    for accessing the API, while also being subject to the prevailing legal
+    framework dictated by local legislation.
+    \
+    It is important to remark that in cases where personal user data is
+    processed by the API, and users can exercise their rights through mechanisms
+    such as opt-in and/or opt-out, the use of 3-legged access tokens becomes
+    mandatory. 
+    This measure ensures that the API remains in strict compliance with user
+    privacy preferences and regulatory obligations,
+    upholding the principles of transparency and user-centric data control.
+    ## 4. API Documentation
+    ## 4.1 Details
+    
+    TBD
+    
+  license:
+    name: Apache 2.0
+    url: https://www.apache.org/licenses/LICENSE-2.0.html
+externalDocs:
+  description: Product documentation at Camara
+  url: https://github.com/camaraproject/CallForwardingSignal
+############################################################################
+#                                     Servers                              #
+############################################################################
+servers:
+  - url: "{apiRoot}/{basePath}"
+    variables:
+      apiRoot:
+        default: http://localhost:9091
+        description: API root
+      basePath:
+        default: call-forwarding-signal/v0
+        description: Base path for the Call Forwarding Signal API
+############################################################################
+#                                     Paths                                #
+############################################################################
+paths:
+  /call-forwardings:
+    post:
+      tags:
+        - Call Forwarding information retrieval
+      security:
+        - openId:
+          - call-forwarding-signal:call-forwardings
+      description: Retrieve the information about call forwarding service active
+       on a phone number     
+      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'
+        '404':
+          $ref: '#/components/responses/Generic404'
+        '500':
+          $ref: '#/components/responses/Generic500'
+        '504':
+          $ref: '#/components/responses/Generic504'
+        "401":
+          $ref: "#/components/responses/Generic401"
+        "403":
+          $ref: "#/components/responses/Generic403"
+        "503":
+          $ref: "#/components/responses/Generic503"
+#######################################################
+#  COMPONENTS
+#######################################################
+components:
+  securitySchemes:
+    openId:
+      type: openIdConnect
+      openIdConnectUrl: https://example.com/.well-known/openid-configuration
+  parameters:
+    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
+######################################################
+#  RESOURCES
+#######################################################
+  schemas:
+    CallForwardingSignal:
+      type: object
+      properties:
+        active:
+          type: boolean
+          description: Indicates if a call forwarding service is active.
+#######################################################
+#  REQUEST
+#######################################################    
+    CreateCallForwardingSignal:
+      type: object
+      properties:
+        phoneNumber:
+          $ref: "#/components/schemas/PhoneNumber"
+#######################################################
+#  TYPES
+#######################################################   
+    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"
+######################################################
+#  RESPONSES
+#######################################################            
+    ErrorInfo:
+      type: object
+      required:
+        - status
+        - code
+        - message
+      properties:
+        status:
+          type: integer
+          description: HTTP status code returned along with this error response
+        code:
+          type: string
+          description: Code given to this error
+        message:
+          type: string
+          description: Detailed error description
+  responses:
+    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
+    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
+    Generic403:
+      description: Client does not have sufficient permission
+      headers:
+        x-correlator:
+          $ref: '#/components/headers/x-correlator'
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/ErrorInfo'
+          examples:
+            PermissionDenied:
+              value:
+                status: 403
+                code: PERMISSION_DENIED
+                message: Client does not have sufficient permissions to perform
+                 this action
+            InvalidTokenContext:
+              value:
+                status: 403
+                code: INVALID_TOKEN_CONTEXT
+                message: Phone number cannot be deducted from access token
+                 context
+    Generic404:
+      description: The specified resource was not found
+      headers:
+        x-correlator:
+          $ref: '#/components/headers/x-correlator'
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/ErrorInfo'
+          example:
+            status: 404
+            code: CALL_FORWARDING.UNKNOWN_PHONE_NUMBER
+            message: Call forwarding check can't be done because the phone
+             number is unknown
+    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
+    Generic504:
+      description: Request time exceeded. If it happens repeatedly, consider
+       reducing the request complexity
+      headers:
+        x-correlator:
+          $ref: '#/components/headers/x-correlator'
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/ErrorInfo'
+          example:
+            status: 504
+            code: TIMEOUT
+            message: Request timeout exceeded. Try later