diff --git a/code/API_definitions/call-forwarding-signal.yaml b/code/API_definitions/call-forwarding-signal.yaml index 2f1389b..e89ed81 100644 --- a/code/API_definitions/call-forwarding-signal.yaml +++ b/code/API_definitions/call-forwarding-signal.yaml @@ -90,64 +90,48 @@ info: the Call Forwarding service using the call-forwardings POST method. An array of strings with the information of the type of active call forwarding services will be provided back via the CallForwardingSignal resource. + # Authorization and authentication - The "Camara Security and Interoperability Profile" provides details of how - an API consumer requests an access token. Please refer to Identity and - Consent Management - (https://github.com/camaraproject/IdentityAndConsentManagement/) - for the released version of the profile. - The specific authorization flows to be used will be agreed upon during the - onboarding process, happening between the API consumer and the API - provider, taking into account the declared purpose for accessing the API, - whilst also being subject to the prevailing legal framework dictated by - local legislation. + The "Camara Security and Interoperability Profile" provides details of how an API consumer requests an access token. Please refer to Identity and Consent Management (https://github.com/camaraproject/IdentityAndConsentManagement/) for the released version of the profile. - In cases where personal 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 three-legged access tokens is mandatory. This ensures that - the API remains in compliance with privacy regulations, upholding the - principles of transparency and user-centric privacy-by-design. + The specific authorization flows to be used will be agreed upon during the onboarding process, happening between the API consumer and the API provider, taking into account the declared purpose for accessing the API, whilst also being subject to the prevailing legal framework dictated by local legislation. + + In cases where personal 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 three-legged access tokens is mandatory. This ensures that the API remains in compliance with privacy regulations, upholding the principles of transparency and user-centric privacy-by-design. + + + # Identifying the phone number from the access token - This API requires the API consumer to identify a phone number as the - subject of the API as follows: - - When the API is invoked using a two-legged access token, the subject - will be identified from the optional `phoneNumber` object field, which - therefore MUST be provided. - - When a three-legged access token is used however, this optional - identifier MUST NOT be provided, as the subject will be uniquely - identified from the access token. - This approach simplifies API usage for API consumers using a - three-legged access token to invoke the API by relying on the - information that is associated with the access token and was - identified during the authentication process. + This API requires the API consumer to identify a phone number as the subject of the API as follows: + - When the API is invoked using a two-legged access token, the subject will be identified from the optional `phoneNumber` field, which therefore MUST be provided. + - When a three-legged access token is used however, this optional identifier MUST NOT be provided, as the subject will be uniquely identified from the access token. + + This approach simplifies API usage for API consumers using a three-legged access token to invoke the API by relying on the information that is associated with the access token and was identified during the authentication process. + ## Error handling: - - If the subject cannot be identified from the access token and the - optional `phoneNumber` object field is not included in the request, then - the server will return an error with the - `422 MISSING_IDENTIFIER` error code. + - If the subject cannot be identified from the access token and the optional `phoneNumber` field is not included in the request, then the server will return an error with the `422 MISSING_IDENTIFIER` error code. - - If the subject can be identified from the access token and the - optional `phoneNumber` object field is also included in the request, then - the server will return an error with the `422 UNNECESSARY_IDENTIFIER` - error code. This will be the case even if the same device is - identified by these two methods, as the server is unable to make - this comparison. + - If the subject can be identified from the access token and the optional `phoneNumber` field is also included in the request, then the server will return an error with the `422 UNNECESSARY_IDENTIFIER` error code. This will be the case even if the same phone number is identified by these two methods, as the server is unable to make this comparison. + + # Additional CAMARA error responses - The list of error codes in this API specification is not exhaustive. - Therefore the API specification may not document some non-mandatory error - statuses as indicated in `CAMARA API Design Guide`. - Please refer to the `CAMARA_common.yaml` of the Commonalities Release - associated to this API version for a complete list of error responses. - The applicable Commonalities Release can be identified in the - `API Readiness Checklist` document associated to this API version. + The list of error codes in this API specification is not exhaustive. Therefore the API specification MAY not document some non-mandatory error statuses as indicated in `CAMARA API Design Guide`. + + Please refer to the `CAMARA_common.yaml` of the Commonalities Release associated to this API version for a complete list of error responses. The applicable Commonalities Release can be identified in the `API Readiness Checklist` document associated to this API version. + + As a specific rule, error `501 - NOT_IMPLEMENTED` can be only a possible error response if it is explicitly documented in the API. + + + + # Request body strictness + + This API rejects requests with JSON request bodies that contain properties not declared in this specification, at any nesting level. Unknown properties result in a `400 INVALID_ARGUMENT` response. + - As a specific rule, error `501 - NOT_IMPLEMENTED` can be only a possible - error response if it is explicitly documented in the API. # FAQ's (FAQs will be added in a later version of the documentation) @@ -172,10 +156,10 @@ servers: # Tags # ############################################################################ tags: - - name: Unconditional Call Forwarding information retrieval + - name: Unconditional Call Forwarding Information Retrieval description: Provides information on Unconditional Call Forwarding settings for the provided phone number (PhoneNumber) - - name: Call Forwarding information retrieval + - name: Call Forwarding Information Retrieval description: Provides information on Call Forwarding settings for the provided phone number (PhoneNumber). ############################################################################ @@ -185,7 +169,7 @@ paths: /unconditional-call-forwardings: post: tags: - - Unconditional Call Forwarding information retrieval + - Unconditional Call Forwarding Information Retrieval security: - openId: - 'call-forwarding-signal:unconditional-call-forwardings:read' @@ -227,7 +211,7 @@ paths: /call-forwardings: post: tags: - - Call Forwarding information retrieval + - Call Forwarding Information Retrieval security: - openId: - 'call-forwarding-signal:call-forwardings:read' @@ -317,6 +301,7 @@ components: type: array items: type: string + description: Type of call forwarding service active for the phone number. enum: - 'inactive' - 'unconditional' @@ -328,10 +313,9 @@ components: - 'conditional_busy' - 'conditional_no_answer' minItems: 1 + maxItems: 5 XCorrelator: - type: string - pattern: ^[a-zA-Z0-9-_:;.\/<>{}]{0,256}$ - example: "b4333c46-49c0-4f62-80d7-f0ef930f1c46" + $ref: "../common/CAMARA_common.yaml#/components/schemas/XCorrelator" ############################################################################ # Request # ############################################################################ @@ -349,33 +333,12 @@ components: # 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" + $ref: "../common/CAMARA_common.yaml#/components/schemas/PhoneNumber" ############################################################################ # Responces # ############################################################################ 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 + $ref: "../common/CAMARA_common.yaml#/components/schemas/ErrorInfo" responses: Generic400: description: Bad Request diff --git a/documentation/API_documentation/call-forwarding-signal-API-Readiness-Checklist.md b/documentation/API_documentation/call-forwarding-signal-API-Readiness-Checklist.md deleted file mode 100644 index 8eecf49..0000000 --- a/documentation/API_documentation/call-forwarding-signal-API-Readiness-Checklist.md +++ /dev/null @@ -1,23 +0,0 @@ - -# API Readiness Checklist - -Checklist for API call-forwarding-signal v0.4.0 in r3.3 - - -| Nr | API release assets | alpha | release-candidate | initial
public | stable
public | Status | Reference information | -|----|----------------------------------------------|:-----:|:-----------------:|:-------:|:------:|:----:|:----| -| 1 | API definition | M | M | M | M | Y | [link](/code/API_definitions/call-forwarding-signal.yaml) | -| 2 | Design guidelines from Commonalities applied | O | M | M | M | Y | [r3.3](https://github.com/camaraproject/Commonalities/releases/tag/r3.3) | -| 3 | Guidelines from ICM applied | O | M | M | M | Y | [r3.3](https://github.com/camaraproject/IdentityAndConsentManagement/releases/tag/r3.3) | -| 4 | API versioning convention applied | M | M | M | M | Y | v0.4.0 | -| 5 | API documentation | M | M | M | M | Y | inline in YAML | -| 6 | User stories | O | O | O | M | Y | [link](/documentation/API_documentation/CFS_UserStory_UseCase-1.md) | -| 7 | Basic API test cases & documentation | O | M | M | M | Y | [call-forwarding-signal-every-forwarding](/code/Test_definitions/call-forwarding-signal-every-forwarding.feature), [call-forwarding-signal-unconditional](/code/Test_definitions/call-forwarding-signal-unconditional.feature) | -| 8 | Enhanced API test cases & documentation | O | O | O | M | Y | [call-forwarding-signal-every-forwarding](/code/Test_definitions/call-forwarding-signal-every-forwarding.feature), [call-forwarding-signal-unconditional](/code/Test_definitions/call-forwarding-signal-unconditional.feature) | -| 9 | Test result statement | O | O | O | M | N | | -| 10 | API release numbering convention applied | M | M | M | M | Y | r3.3 | -| 11 | Change log updated | M | M | M | M | Y | [link](/CHANGELOG.md) | -| 12 | Previous public-release was certified | O | O | O | M | N | | -| 13 | API description (for marketing) | O | O | M | M | Y | [wiki link](https://lf-camaraproject.atlassian.net/wiki/x/uoDVB) | - -The documentation for the content of the checklist is here: see API Readiness Checklist section in the [API Release Process](https://lf-camaraproject.atlassian.net/wiki/x/jine). \ No newline at end of file