Add files via upload

code/API_definitions/Traffic Influence/Call_Forwarding_Signal.yaml

@@ -5,7 +5,7 @@ openapi: 3.0.3
 ############################################################################
 info:
   title: Call Forwarding Signal API
-  version: 0.1.3-wip
+  version: 0.1.5-wip
   description: |
     ## Overview
     The Call Forwarding Signal (CFS) API provides the API Consumer with an
@@ -16,13 +16,21 @@ info:
     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.
+    for a specific phone number.\
+    \
+    **Example use cases:**\
+    \
+    [**Bank Frauds**](https://github.com/camaraproject/CallForwardingSignal/\
+    blob/main/documentation/API_documentation/CFS_UserStory_UseCase-1.md)\
+    \
+    [**Telecommunication Frauds**](https://github.com/camaraproject/\
+    CallForwardingSignal/discussions/3#discussioncomment-8701847)
     ## 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
+    with the phone number on which the Call Forwarding Service status must be
     verified.
-    A responce is provided by the API Producer with an resource, CallForwordings
+    A response is provided by the API Producer with a resource, CallForwardings
     , containing a boolean with the status beeing active or not.\
     \
     Before starting to use the Call Forwarding API, the developer needs to know
@@ -37,13 +45,13 @@ info:
     This is the end user phone number. The CFS API verifies if a call forwarding
     service is active on this phone number.\
     \
-    **CreateCallForwordingSignal**
+    **CreateCallForwardingSignal**
     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.\
+    be verified about the status of the Network Call Forwarding service.\
     \
-    **CallForwordingSignal**
+    **CallForwardingSignal**
     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\
+    This Resource contains the status of the Network Call Forwarding service for\
     the specified phone number.
     ## 3. Authorization and authentication
     CAMARA guidelines defines a set of authorization flows which can grant API
@@ -66,10 +74,24 @@ info:
     upholding the principles of transparency and user-centric data control.
     ## 4. API Documentation
     ## 4.1 Details
-    TBD
+    The CFS API is invoked by an API Consumer after the Consent Management flow
+    described in chapter 3.
+    The API Consumer creates a resource (CreateCallForwardingSignal) with the
+    "/call-forwardings" POST method. In this resource the phone number
+    (PhoneNumber) to be checked is provided by the API Consumer.
+    The consent on the usage of the phone number must be provided to the API
+    Consumer by the owner of the phone number via the Consent Management
+    procedure described in chapter 3.
+    The CFS API Producer ...... (TBD - ongoing discussion)
+    ## 4.2 FAQ's
+    (FAQs will be added in a later version of the documentation)
+    ## 4.3 Release Notes
+    First draft for the CFS API.
   license:
     name: Apache 2.0
     url: https://www.apache.org/licenses/LICENSE-2.0.html
+  contact:
+    email: [email protected]
 externalDocs:
   description: Product documentation at Camara
   url: https://github.com/camaraproject/CallForwardingSignal
@@ -86,6 +108,13 @@ servers:
         default: call-forwarding-signal/v0
         description: Base path for the Call Forwarding Signal API
 ############################################################################
+#                                     Tags                                #
+############################################################################
+tags:
+  - name: Call Forwarding information retrieval
+    description: Reads the configured Call Forwarding settings for the
+     provided phone number (PhoneNumber)
+############################################################################
 #                                     Paths                                #
 ############################################################################
 paths:
@@ -96,8 +125,9 @@ paths:
       security:
         - openId:
             - 'call-forwarding-signal:call-forwardings:read'
-      description: Retrieve the information about call forwarding service active
+      summary: Retrieve the information about call forwarding service active
        on a phone number
+      description: TBD
       operationId: retrieveCallForwarding
       parameters:
         - $ref: '#/components/parameters/x-correlator'
@@ -117,6 +147,8 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/CallForwardingSignal'
+        "400":
+          $ref: "#/components/responses/Generic400"
         '404':
           $ref: '#/components/responses/Generic404'
         '500':
@@ -135,6 +167,7 @@ paths:
 components:
   securitySchemes:
     openId:
+      description: to support Consent Management
       type: openIdConnect
       openIdConnectUrl: https://example.com/.well-known/openid-configuration
   parameters:
@@ -154,6 +187,8 @@ components:
   ############################################################################
   schemas:
     CallForwardingSignal:
+      description: resource containing the information about the Call
+       Forwarding Service for the given phone number (PhoneNumber)
       type: object
       properties:
         active:
@@ -163,6 +198,8 @@ components:
     #                                 Request                                  #
     ############################################################################
     CreateCallForwardingSignal:
+      description: resource containing the phone number (PhoneNumber) regarding
+       which the Call Forwarding Service must be checked
       type: object
       properties:
         phoneNumber:
@@ -183,6 +220,7 @@ components:
     #                                 Responces                                #
     ############################################################################
     ErrorInfo:
+      description: error information
       type: object
       required:
         - status
@@ -302,4 +340,4 @@ components:
           example:
             status: 504
             code: TIMEOUT
-            message: Request timeout exceeded. Try later
+            message: Request timeout exceeded. Try later