Initial API proposal (for merging proposed YAML of PR#9)

code/API_definitions/number-recycling.yaml

@@ -0,0 +1,315 @@
+openapi: 3.0.3
+info:
+  title: Number Recycling
+  description: |
+    The API can be used to check whether the subscriber of the phone number has changed.
+    A common scenario is when Application service provider (ASP) wants to check whether there has been a change in the user associated with the phone number after the specified date. This allows the ASP to ensure that a phone number is correctly linked to an user and prevent the mis-delivery of SMS messages.
+
+    For example, below is a potential scenarios:
+    * Scenario 1
+      * Pre-conditions
+        * User A signed a contract with MNO A for the phone number '+123456789' on October 9, 2023, and is still using it.
+        * User A also signed contracts with ASP A on December 22, 2023 for its services.
+        * ASP A holds the contract date (2023-12-22) and the phone number (+123456789) for User A.
+        * Currently, on November 2, 2024, ASP A wishes to send a SMS message to User A.
+      * Potential operations
+        * ASP A sends a request with specified date (2023-12-22) and phone number (+123456789) to the Number Recycling API.
+        * The API response sets to 'false', indicating that there has not been a change in the user associated with the phone number.
+      * Post-conditions
+        * ASP A decides to send the SMS message to User A.
+      * By following these steps, ASP A ensures that a phone number is linked to User A.
+
+    <img width="4000" alt="Number_Recycling_scenario_1" src="https://raw.githubusercontent.com/camaraproject/NumberRecycling/main/documentation/API_documentation/assets/Number_Recycling_scenario_1.png">
+
+      * Scenario 2
+        * Pre-conditions
+          * User A signed a contract with MNO A for the phone number '+123456789' on October 9, 2023, and canceled it on February 25, 2024. Subsequently, User B signed a contract with MNO A for the same phone number on September 21, 2024, and is still using it.
+          * User A also signed contracts with ASP A on December 22, 2023 for its services.
+          * ASP A holds the contract date (2023-12-22) and the phone number (+123456789) for User A.
+          * Currently, on November 2, 2024, ASP A wishes to send a SMS message to User A.
+        * Potential operations
+          * ASP A sends a request with specified date (2023-12-22) and phone number (+123456789) to the Number Recycling API.
+          * The API response sets to 'true', indicating that there has been a change in the user associated with the phone number.
+        * Post-conditions
+          * ASP A decides to stop sending the SMS message to User A and contacts User A by mail.
+        * By following these steps, ASP A ensures that a phone number is not linked to User A and prevents the mis-delivery of the SMS message.
+
+    <img width="4000" alt="Number_Recycling_scenario_2" src="https://raw.githubusercontent.com/camaraproject/NumberRecycling/main/documentation/API_documentation/assets/Number_Recycling_scenario_2.png">
+
+    Note:
+    * When the API receives a request with specified date during which there is no contract with MNO for the phone number, the API respond sets to 'true'(e.g., the period between 2024-02-25 and 2024-09-21 in the Scenario 2 of the figure above).
+
+    ### Authorization and authentication
+
+    The "Camara Security and Interoperability Profile" provides details on how a client requests an access token. Please refer to Identify and Consent Management (https://github.com/camaraproject/IdentityAndConsentManagement/) for the released version of the Profile.
+
+    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.
+
+    # Identifying a phone number from the access token
+
+    This specification defines the `phoneNumber` field as optional in API requests, specifically in cases where the API is accessed using a 3-legged access token, and the phone number can be uniquely identified by the token. This approach simplifies API usage for API consumers by relying on the information associated with the access token used to invoke the API.
+
+    ## Handling of phone number information:
+
+    ### Optional `phoneNumber` field for 3-legged tokens:
+
+    - When using a 3-legged access token, the phone number associated with the access token must be considered as the phone number for the API request. This means that the `phoneNumber` field is not required in the request, and if included it must identify the same phone number, therefore **it is recommended NOT to include it in these scenarios** to simplify the API usage and avoid additional validations.
+
+    ### Validation mechanism:
+
+    - The server will extract the phone number identification from the access token, if available.
+    - If the API request additionally includes a `phoneNumber` field when using a 3-legged access token, the API will validate that the phone number provided matches the one associated with the access token.
+    - If there is a mismatch, the API will respond with a 403 - INVALID_TOKEN_CONTEXT error, indicating that the phone number information in the request does not match the token.
+
+    ### Error handling for unidentifiable phone number:
+
+    - If the `phoneNumber` field is not included in the request and the phone number information cannot be derived from the 3-legged access token, the server will return a 422 `UNIDENTIFIABLE_PHONE_NUMBER` error.
+
+    ### Restrictions for tokens without an associated authenticated phone number:
+
+     For scenarios which do not have a phone number associated to the token during the authentication flow, e.g. 2-legged access tokens, the `phoneNumber` field MUST be provided in the API request. This ensures that the phone number is explicit and valid for each API call made with these tokens.
+
+  version: wip
+  x-camara-commonalities: 0.4.0
+  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/NumberRecycling
+servers:
+  - url: '{apiRoot}/number-recycling/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`
+paths:
+  /check:
+    post:
+      security:
+        - openId:
+            - number-recycling:check
+      tags:
+        - Check Number Recycling
+      description: Check whether the subscriber of the phone number has changed.
+      operationId: checkNumberRecycling
+      parameters:
+        - $ref: '#/components/parameters/x-correlator'
+      requestBody:
+        description: |
+          Check whether the subscriber of the phone number has changed.
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateCheckNumRecycling'
+        required: true
+      responses:
+        '200':
+          $ref: '#/components/responses/Generic200'
+        '400':
+          $ref: '#/components/responses/Generic400'
+        '401':
+          $ref: '#/components/responses/Generic401'
+        '403':
+          $ref: '#/components/responses/Generic403'
+        '404':
+          $ref: '#/components/responses/Generic404'
+        '422':
+          $ref: '#/components/responses/Generic422'
+        '500':
+          $ref: '#/components/responses/Generic500'
+        '503':
+          $ref: '#/components/responses/Generic503'
+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
+  schemas:
+    CreateCheckNumRecycling:
+      type: object
+      required:
+        - specifiedDate
+      properties:
+        phoneNumber:
+          $ref: '#/components/schemas/PhoneNumber'
+        specifiedDate:
+          type: string
+          format: date
+          description: Specified date to check whether there has been a change in the subscriber associated with the specific phone number, in RFC 3339 calendar date format (YYYY-MM-DD).
+          example: "2024-10-31"
+    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"
+    CheckNumRecyclingInfo:
+      type: object
+      required:
+        - phoneNumChanged
+      properties:
+        phoneNumChanged:
+          type: boolean
+          description: |
+            Set to true (Boolean, not string) when there has been a change in the subscriber associated with the specific phone number after “specifiedDate”.
+    ErrorInfo:
+      type: object
+      required:
+        - status
+        - code
+        - detail
+      properties:
+        status:
+          type: integer
+          description: HTTP response status code
+        code:
+          type: string
+          description: Code given to this error
+        detail:
+          type: string
+          description: Detailed error description
+  responses:
+    Generic200:
+      description: OK
+      headers:
+        x-correlator:
+          description: Correlation id for the different services
+          schema:
+            type: string
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/CheckNumRecyclingInfo'
+    Generic400:
+      description: Problem with the client request
+      headers:
+        x-correlator:
+          description: Correlation id for the different services
+          schema:
+            type: string
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/ErrorInfo'
+          example:
+            status: 400
+            code: INVALID_ARGUMENT
+            detail: Client specified an invalid argument, request body or query param
+    Generic401:
+      description: Authentication problem with the client request
+      headers:
+        x-correlator:
+          description: Correlation id for the different services
+          schema:
+            type: string
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/ErrorInfo'
+          example:
+            status: 401
+            code: UNAUTHENTICATED
+            detail: Request not authenticated due to missing, invalid, or expired credentials
+    Generic403:
+      description: Client does not have sufficient permission
+      headers:
+        x-correlator:
+          description: Correlation id for the different services
+          schema:
+            type: string
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/ErrorInfo'
+          examples:
+            PermissionDenied:
+              value:
+                status: 403
+                code: PERMISSION_DENIED
+                detail: Client does not have sufficient permissions to perform this action
+            InvalidTokenContext:
+              value:
+                status: 403
+                code: INVALID_TOKEN_CONTEXT
+                detail: Phone number cannot be deducted from access token context
+    Generic404:
+      description: Resource Not Found
+      headers:
+        x-correlator:
+          description: Correlation id for the different services
+          schema:
+            type: string
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/ErrorInfo'
+          example:
+            status: 404
+            code: NOT_FOUND
+            detail: A specified resource is not found
+    Generic422:
+      description: Unprocessable Content
+      headers:
+        x-correlator:
+          description: Correlation id for the different services
+          schema:
+            type: string
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/ErrorInfo'
+          examples:
+            NotSupported:
+              value:
+                status: 422
+                code: NOT_SUPPORTED
+                detail: Service not supported for this phoneNumber
+            UnidentifiablePhoneMumber:
+              value:
+                status: 422
+                code: UNIDENTIFIABLE_PHONE_NUMBER
+                detail: The phone number cannot be identified
+    Generic500:
+      description: Server error
+      headers:
+        x-correlator:
+          description: Correlation id for the different services
+          schema:
+            type: string
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/ErrorInfo'
+          example:
+            status: 500
+            code: INTERNAL
+            detail: Server error
+    Generic503:
+      description: Service unavailable. Typically the server is down.
+      headers:
+        x-correlator:
+          description: Correlation id for the different services
+          schema:
+            type: string
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/ErrorInfo'
+          example:
+            status: 503
+            code: UNAVAILABLE
+            detail: Service unavailable