From 255d88931b188fcf8c359f4b3ee3becd162cc841 Mon Sep 17 00:00:00 2001 From: Herbert Damker <52109189+hdamker@users.noreply.github.com> Date: Fri, 19 Jul 2024 18:14:28 +0200 Subject: [PATCH 01/27] Update quality-on-demand.yaml Add documentation about "Handling of device information" within the API description. Made device parameter optional. --- code/API_definitions/quality-on-demand.yaml | 34 ++++++++++++++++++--- 1 file changed, 29 insertions(+), 5 deletions(-) diff --git a/code/API_definitions/quality-on-demand.yaml b/code/API_definitions/quality-on-demand.yaml index 1b41ac6653..7889418152 100644 --- a/code/API_definitions/quality-on-demand.yaml +++ b/code/API_definitions/quality-on-demand.yaml @@ -61,9 +61,34 @@ info: 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 device from the access token + + This specification defines the `device` object field as optional in API requests, specifically in cases where the API is accessed using a 3-legged access token, and the device can be uniquely identified by the token. This approach simplifies API usage for API consumers by relying on the device information associated with the access token used to invoke the API. + + ## Handling of device information: + + ### Optional device object for 3-legged tokens: + + - When using a 3-legged access token, the device associated with the access token must be considered as the device for the API request. This means that the device object is not required in the request, and if included it must identify the same device, 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 device identification from the access token, if available. + - If the API request additionally includes a `device` object when using a 3-legged access token, the API will validate that the device identifier 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 device information in the request does not match the token. + + ### Error handling for unidentifiable devices: + + - If the `device` object is not included in the request and the device information cannot be derived from the 3-legged access token, the server will return a 422 `UNIDENTIFIABLE_DEVICE` error. + + ### Restrictions for tokens without an associated authenticated identifier: + + - For scenarios which do not have a single device identifier associated to the token during the authentication flow, e.g. 2-legged access tokens, the `device` object MUST be provided in the API request. This ensures that the device identification is explicit and valid for each API call made with these tokens. + # Further info and support (FAQs will be added in a later version of the documentation) + license: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0.html @@ -106,7 +131,7 @@ paths: - In case of a `QOS_STATUS_CHANGED` event with `qosStatus` as `UNAVAILABLE` and `statusInfo` as `NETWORK_TERMINATED` the resources of the QoS session are not directly released, but will get deleted automatically at earliest 360 seconds after the event. This behavior allows clients which are not receiving notification events but are polling to get the session information with the `qosStatus` `UNAVAILABLE` and `statusInfo` `NETWORK_TERMINATED`. Before a client can attempt to create a new QoD session for the same device and flow period they must release the session resources with an explicit `delete` operation if not yet automatically deleted. - - The access token may be either 2-legged or 3-legged. If a 3-legged access token is used, the end user identified by the `device` parameter must also be associated with the access token. + - The access token may be either 2-legged or 3-legged. If a 3-legged access token which is associated with a device is used, it is recommended NOT to include the `device` parameter in the request (see "Handling of device information" within the API description for details). operationId: createSession security: @@ -267,7 +292,7 @@ paths: Querying for QoS session resource information details **NOTES:** - - The access token may be either 2-legged or 3-legged. If a 3-legged access token is used, the end user associated with the session must also be associated with the access token. + - The access token may be either 2-legged or 3-legged. If a 3-legged access token is used, the end user (and device) associated with the session must also be associated with the access token. operationId: getSession security: @@ -324,7 +349,7 @@ paths: There will be no notification event if the `qosStatus` was already `UNAVAILABLE`. **NOTES:** - - The access token may be either 2-legged or 3-legged. If a 3-legged access token is used, the end user associated with the session must also be associated with the access token. + - The access token may be either 2-legged or 3-legged. If a 3-legged access token is used, the end user (and device) associated with the session must also be associated with the access token. operationId: deleteSession security: @@ -373,7 +398,7 @@ paths: - New overall session duration: 50,000 seconds (the maximum allowed) **NOTES:** - - The access token may be either 2-legged or 3-legged. If a 3-legged access token is used, the end user associated with the session must also be associated with the access token. + - The access token may be either 2-legged or 3-legged. If a 3-legged access token is used, the end user (and device) associated with the session must also be associated with the access token. operationId: extendQosSessionDuration security: @@ -506,7 +531,6 @@ components: example: "c8974e592c2fa383d4a3960714" description: Authentication token for callback API required: - - device - applicationServer - qosProfile From d8031d4b4aabe9ef89851e74a2330f38a7f3bd0c Mon Sep 17 00:00:00 2001 From: Herbert Damker <52109189+hdamker@users.noreply.github.com> Date: Fri, 19 Jul 2024 18:21:28 +0200 Subject: [PATCH 02/27] Update quality-on-demand.yaml Aligned Device object and info with Commonalities --- code/API_definitions/quality-on-demand.yaml | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/code/API_definitions/quality-on-demand.yaml b/code/API_definitions/quality-on-demand.yaml index 7889418152..0ea2ce1a8d 100644 --- a/code/API_definitions/quality-on-demand.yaml +++ b/code/API_definitions/quality-on-demand.yaml @@ -89,10 +89,13 @@ info: (FAQs will be added in a later version of the documentation) + version: wip + license: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0.html - version: wip + + x-camara-commonalities: 0.4.0 externalDocs: description: Product documentation at Camara @@ -751,7 +754,8 @@ components: * `phoneNumber` * `networkAccessIdentifier` - NOTE: the MNO might support only a subset of these options. The API invoker can provide multiple identifiers to be compatible across different MNOs. In this case the identifiers MUST belong to the same device + NOTE1: the MNO might support only a subset of these options. The API invoker can provide multiple identifiers to be compatible across different MNOs. In this case the identifiers MUST belong to the same device + NOTE2: for the Commonalities release v0.4, we are enforcing that the networkAccessIdentifier is only part of the schema for future-proofing, and CAMARA does not currently allow its use. After the CAMARA meta-release work is concluded and the relevant issues are resolved, its use will need to be explicitly documented in the guidelines. type: object properties: phoneNumber: From 17712dd5ddd06d3816ae771f282d14f425912d11 Mon Sep 17 00:00:00 2001 From: Herbert Damker <52109189+hdamker@users.noreply.github.com> Date: Fri, 19 Jul 2024 18:53:45 +0200 Subject: [PATCH 03/27] Update quality-on-demand.yaml Updated errorMessage according to Commonalities. Added 422, removed 501 (not used). Reduced 400 examples within createSession to the ones not covered by other codes according to chapter 6.2 of Design Guidelines. --- code/API_definitions/quality-on-demand.yaml | 121 +++++++++++--------- 1 file changed, 68 insertions(+), 53 deletions(-) diff --git a/code/API_definitions/quality-on-demand.yaml b/code/API_definitions/quality-on-demand.yaml index 0ea2ce1a8d..24427ef9d6 100644 --- a/code/API_definitions/quality-on-demand.yaml +++ b/code/API_definitions/quality-on-demand.yaml @@ -223,24 +223,6 @@ paths: status: 400 code: INVALID_ARGUMENT message: "Expected property is missing: device" - InsufficientDeviceProperties: - summary: Device must be identified by at least one parameter - value: - status: 400 - code: INVALID_ARGUMENT - message: "Insufficient properties specified: device" - InconsistentDeviceProperties: - summary: Device parameters provided identify different devices - value: - status: 400 - code: INVALID_ARGUMENT - message: "Multiple inconsistent parameters specified: device" - CannotIdentifyDevice: - summary: No device can be identified from provided parameters - value: - status: 400 - code: INVALID_ARGUMENT - message: "Unable to identify device from specified parameters: device" InvalidDevicePublicPortValue: summary: Invalid port specified for device public port value: @@ -277,12 +259,12 @@ paths: $ref: "#/components/responses/Generic403" "409": $ref: "#/components/responses/SessionInConflict409" + "422": + $ref: "#/components/responses/Generic422" "429": $ref: "#/components/responses/Generic429" "500": $ref: "#/components/responses/Generic500" - "501": - $ref: "#/components/responses/Generic501" "503": $ref: "#/components/responses/Generic503" @@ -899,46 +881,73 @@ components: responses: Generic400: - description: Invalid input + description: Bad Request headers: x-correlator: - $ref: '#/components/headers/x-correlator' + $ref: "#/components/headers/x-correlator" content: application/json: schema: $ref: "#/components/schemas/ErrorInfo" - example: - status: 400 - code: INVALID_ARGUMENT - message: "Schema validation failed at ..." + 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. + GENERIC_400_OUT_OF_RANGE: + description: Out of Range. Specific Syntax Exception used when a given field has a pre-defined range or a invalid filter criteria combination is requested + value: + status: 400 + code: OUT_OF_RANGE + message: Client specified an invalid range. Generic401: description: Unauthorized headers: x-correlator: - $ref: '#/components/headers/x-correlator' + $ref: "#/components/headers/x-correlator" content: application/json: schema: $ref: "#/components/schemas/ErrorInfo" - example: - status: 401 - code: UNAUTHENTICATED - message: "Authorization failed: ..." + examples: + GENERIC_401_UNAUTHENTICATED: + description: Request cannot be authenticated + value: + status: 401 + code: UNAUTHENTICATED + message: Request not authenticated due to missing, invalid, or expired credentials. + GENERIC_401_AUTHENTICATION_REQUIRED: + description: New authentication is needed, authentication is no longer valid + value: + status: 401 + code: AUTHENTICATION_REQUIRED + message: New authentication is required. Generic403: description: Forbidden headers: x-correlator: - $ref: '#/components/headers/x-correlator' + $ref: "#/components/headers/x-correlator" content: application/json: schema: $ref: "#/components/schemas/ErrorInfo" - example: - status: 403 - code: PERMISSION_DENIED - message: "Operation not allowed: ..." + 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. + GENERIC_403_INVALID_TOKEN_CONTEXT: + description: Reflect some inconsistency between information in some field of the API and the related OAuth2 Token + value: + status: 403 + code: INVALID_TOKEN_CONTEXT + message: "{{field}} is not consistent with access token." SessionNotFound404: description: Session not found @@ -968,6 +977,29 @@ components: code: CONFLICT message: Conflict with an existing session for the same device. + Generic422: + description: Unprocessable Content + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + examples: + GENERIC_422_DEVICE_IDENTIFIERS_MISMATCH: + description: Inconsistency between device identifiers not pointing to the same device + value: + status: 422 + code: DEVICE_IDENTIFIERS_MISMATCH + message: Provided device identifiers are not consistent. + GENERIC_422_DEVICE_NOT_APPLICABLE: + description: Service is not available for the provided device + value: + status: 422 + code: DEVICE_NOT_APPLICABLE + message: The service is not available for the provided device. + Generic429: description: Too Many Requests headers: @@ -1005,23 +1037,6 @@ components: code: INTERNAL message: "Internal server error: ..." - Generic501: - description: Not Implemented - headers: - x-correlator: - $ref: '#/components/headers/x-correlator' - content: - application/json: - schema: - $ref: "#/components/schemas/ErrorInfo" - 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. - Generic503: description: Service Unavailable headers: From e23a590eb6e441039e3cb85ec1d886ec019e46c4 Mon Sep 17 00:00:00 2001 From: Herbert Damker <52109189+hdamker@users.noreply.github.com> Date: Fri, 19 Jul 2024 19:17:58 +0200 Subject: [PATCH 04/27] Update quality-on-demand.yaml Removing trailing spaces --- code/API_definitions/quality-on-demand.yaml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/code/API_definitions/quality-on-demand.yaml b/code/API_definitions/quality-on-demand.yaml index 24427ef9d6..703cc977b8 100644 --- a/code/API_definitions/quality-on-demand.yaml +++ b/code/API_definitions/quality-on-demand.yaml @@ -84,17 +84,17 @@ info: ### Restrictions for tokens without an associated authenticated identifier: - For scenarios which do not have a single device identifier associated to the token during the authentication flow, e.g. 2-legged access tokens, the `device` object MUST be provided in the API request. This ensures that the device identification is explicit and valid for each API call made with these tokens. - + # Further info and support (FAQs will be added in a later version of the documentation) - + version: wip license: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0.html - + x-camara-commonalities: 0.4.0 externalDocs: From c8b843a3f9979b87d98d6bb4b6e64b7494260222 Mon Sep 17 00:00:00 2001 From: Herbert Damker <52109189+hdamker@users.noreply.github.com> Date: Mon, 29 Jul 2024 19:13:26 +0200 Subject: [PATCH 05/27] Update quality-on-demand.yaml Added error messages from Commonalities in 404, 422 --- code/API_definitions/quality-on-demand.yaml | 35 +++++++++++++++------ 1 file changed, 25 insertions(+), 10 deletions(-) diff --git a/code/API_definitions/quality-on-demand.yaml b/code/API_definitions/quality-on-demand.yaml index b76e234740..b7612ef825 100644 --- a/code/API_definitions/quality-on-demand.yaml +++ b/code/API_definitions/quality-on-demand.yaml @@ -315,7 +315,7 @@ paths: "403": $ref: "#/components/responses/Generic403" "404": - $ref: "#/components/responses/SessionNotFound404" + $ref: "#/components/responses/Generic404" "429": $ref: "#/components/responses/Generic429" "500": @@ -363,7 +363,7 @@ paths: "403": $ref: "#/components/responses/Generic403" "404": - $ref: "#/components/responses/SessionNotFound404" + $ref: "#/components/responses/Generic404" "429": $ref: "#/components/responses/Generic429" "500": @@ -443,7 +443,7 @@ paths: "403": $ref: "#/components/responses/Generic403" "404": - $ref: "#/components/responses/SessionNotFound404" + $ref: "#/components/responses/Generic404" "429": $ref: "#/components/responses/Generic429" "500": @@ -951,19 +951,28 @@ components: code: INVALID_TOKEN_CONTEXT message: "{{field}} is not consistent with access token." - SessionNotFound404: - description: Session not found + Generic404: + description: Not found headers: x-correlator: - $ref: '#/components/headers/x-correlator' + $ref: "#/components/headers/x-correlator" content: application/json: schema: $ref: "#/components/schemas/ErrorInfo" - example: - status: 404 - code: NOT_FOUND - message: "Session Id does not exist" + 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_DEVICE_NOT_FOUND: + description: Device identifier not found + value: + status: 404 + code: DEVICE_NOT_FOUND + message: Device identifier not found. SessionInConflict409: description: Conflict @@ -1001,6 +1010,12 @@ components: status: 422 code: DEVICE_NOT_APPLICABLE message: The service is not available for the provided device. + GENERIC_422_UNIDENTIFIABLE_DEVICE: + description: Service is not available for the provided device + value: + status: 422 + code: UNIDENTIFIABLE_DEVICE + message: The device cannot be identified. Generic429: description: Too Many Requests From 868c06c75ea192ff8b0fb6178a72761a568eb266 Mon Sep 17 00:00:00 2001 From: Herbert Damker <52109189+hdamker@users.noreply.github.com> Date: Mon, 29 Jul 2024 19:16:37 +0200 Subject: [PATCH 06/27] Update quality-on-demand.yaml space removed after colon --- code/API_definitions/quality-on-demand.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/code/API_definitions/quality-on-demand.yaml b/code/API_definitions/quality-on-demand.yaml index b7612ef825..f44b2b2f90 100644 --- a/code/API_definitions/quality-on-demand.yaml +++ b/code/API_definitions/quality-on-demand.yaml @@ -1014,7 +1014,7 @@ components: description: Service is not available for the provided device value: status: 422 - code: UNIDENTIFIABLE_DEVICE + code: UNIDENTIFIABLE_DEVICE message: The device cannot be identified. Generic429: From b349cda11695b996bdde288c1fdf43ddd4445cdc Mon Sep 17 00:00:00 2001 From: Herbert Damker <52109189+hdamker@users.noreply.github.com> Date: Mon, 29 Jul 2024 19:47:08 +0200 Subject: [PATCH 07/27] Update quality-on-demand.yaml Added description for SessionInfo schema to address #328 --- code/API_definitions/quality-on-demand.yaml | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/code/API_definitions/quality-on-demand.yaml b/code/API_definitions/quality-on-demand.yaml index f44b2b2f90..df490bf121 100644 --- a/code/API_definitions/quality-on-demand.yaml +++ b/code/API_definitions/quality-on-demand.yaml @@ -522,7 +522,11 @@ components: - qosProfile SessionInfo: - description: Session related information. + description: | + Session related information returned in responses. + Within the optional device object only one identifier will be returned (with the original value provided in CreateSession). + If no device identifier was provided in CreateSession (together with a 3-legged token), no device object will be returned in SessionInfo. + Please note that IP addresses of devices can change and get reused and can't be used in these cases again to identify the same device. allOf: - $ref: "#/components/schemas/BaseSessionInfo" - type: object From d6bfb3277e49754eb72a68eb230804ee1469c808 Mon Sep 17 00:00:00 2001 From: Herbert Damker <52109189+hdamker@users.noreply.github.com> Date: Mon, 29 Jul 2024 19:49:40 +0200 Subject: [PATCH 08/27] Update quality-on-demand.yaml Remove trailing space --- code/API_definitions/quality-on-demand.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/code/API_definitions/quality-on-demand.yaml b/code/API_definitions/quality-on-demand.yaml index df490bf121..2ab88f7674 100644 --- a/code/API_definitions/quality-on-demand.yaml +++ b/code/API_definitions/quality-on-demand.yaml @@ -523,7 +523,7 @@ components: SessionInfo: description: | - Session related information returned in responses. + Session related information returned in responses. Within the optional device object only one identifier will be returned (with the original value provided in CreateSession). If no device identifier was provided in CreateSession (together with a 3-legged token), no device object will be returned in SessionInfo. Please note that IP addresses of devices can change and get reused and can't be used in these cases again to identify the same device. From 498ff43ee81afe8d39a1535a9257b76cea1a08df Mon Sep 17 00:00:00 2001 From: Herbert Damker <52109189+hdamker@users.noreply.github.com> Date: Mon, 29 Jul 2024 19:57:05 +0200 Subject: [PATCH 09/27] Update quality-on-demand.yaml Added clarification to all relevant endpoints: "The session must must have been created by the same API client given in the access token" --- code/API_definitions/quality-on-demand.yaml | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/code/API_definitions/quality-on-demand.yaml b/code/API_definitions/quality-on-demand.yaml index 2ab88f7674..5b3dad88df 100644 --- a/code/API_definitions/quality-on-demand.yaml +++ b/code/API_definitions/quality-on-demand.yaml @@ -279,7 +279,9 @@ paths: Querying for QoS session resource information details **NOTES:** - - The access token may be either 2-legged or 3-legged. If a 3-legged access token is used, the end user (and device) associated with the session must also be associated with the access token. + - The access token may be either 2-legged or 3-legged. + - If a 3-legged access token is used, the end user (and device) associated with the session must also be associated with the access token. + - The session must must have been created by the same API client given in the access token operationId: getSession security: @@ -336,7 +338,9 @@ paths: There will be no notification event if the `qosStatus` was already `UNAVAILABLE`. **NOTES:** - - The access token may be either 2-legged or 3-legged. If a 3-legged access token is used, the end user (and device) associated with the session must also be associated with the access token. + - The access token may be either 2-legged or 3-legged. + - If a 3-legged access token is used, the end user (and device) associated with the session must also be associated with the access token. + - The session must must have been created by the same API client given in the access token operationId: deleteSession security: @@ -385,7 +389,9 @@ paths: - New overall session duration: 50,000 seconds (the maximum allowed) **NOTES:** - - The access token may be either 2-legged or 3-legged. If a 3-legged access token is used, the end user (and device) associated with the session must also be associated with the access token. + - The access token may be either 2-legged or 3-legged. + - If a 3-legged access token is used, the end user (and device) associated with the session must also be associated with the access token. + - The session must must have been created by the same API client given in the access token operationId: extendQosSessionDuration security: From 74d1fe9842d056b068de07896921b895af0d606c Mon Sep 17 00:00:00 2001 From: Herbert Damker <52109189+hdamker@users.noreply.github.com> Date: Mon, 29 Jul 2024 19:59:45 +0200 Subject: [PATCH 10/27] Update quality-on-demand.yaml Removed trailing space --- code/API_definitions/quality-on-demand.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/code/API_definitions/quality-on-demand.yaml b/code/API_definitions/quality-on-demand.yaml index 5b3dad88df..dcb6814235 100644 --- a/code/API_definitions/quality-on-demand.yaml +++ b/code/API_definitions/quality-on-demand.yaml @@ -279,7 +279,7 @@ paths: Querying for QoS session resource information details **NOTES:** - - The access token may be either 2-legged or 3-legged. + - The access token may be either 2-legged or 3-legged. - If a 3-legged access token is used, the end user (and device) associated with the session must also be associated with the access token. - The session must must have been created by the same API client given in the access token From c69ea172e9cd713a90a3df170eb4112ea4ff7a83 Mon Sep 17 00:00:00 2001 From: Herbert Damker <52109189+hdamker@users.noreply.github.com> Date: Mon, 29 Jul 2024 20:02:39 +0200 Subject: [PATCH 11/27] Update quality-on-demand.yaml More trailing spaces deleted --- code/API_definitions/quality-on-demand.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/code/API_definitions/quality-on-demand.yaml b/code/API_definitions/quality-on-demand.yaml index dcb6814235..9bcf9280f9 100644 --- a/code/API_definitions/quality-on-demand.yaml +++ b/code/API_definitions/quality-on-demand.yaml @@ -338,7 +338,7 @@ paths: There will be no notification event if the `qosStatus` was already `UNAVAILABLE`. **NOTES:** - - The access token may be either 2-legged or 3-legged. + - The access token may be either 2-legged or 3-legged. - If a 3-legged access token is used, the end user (and device) associated with the session must also be associated with the access token. - The session must must have been created by the same API client given in the access token @@ -389,7 +389,7 @@ paths: - New overall session duration: 50,000 seconds (the maximum allowed) **NOTES:** - - The access token may be either 2-legged or 3-legged. + - The access token may be either 2-legged or 3-legged. - If a 3-legged access token is used, the end user (and device) associated with the session must also be associated with the access token. - The session must must have been created by the same API client given in the access token From 52789742f0f043d701ab8c7e28dcaec764c4ae13 Mon Sep 17 00:00:00 2001 From: Herbert Damker <52109189+hdamker@users.noreply.github.com> Date: Mon, 29 Jul 2024 20:18:34 +0200 Subject: [PATCH 12/27] Update qos-profiles.yaml Added (mandatory) description in info object about "Identifying a device from the access token" Updated most error messages with copies from https://github.com/camaraproject/Commonalities/blob/main/artifacts/CAMARA_common.yaml --- code/API_definitions/qos-profiles.yaml | 164 +++++++++++++++++++++---- 1 file changed, 137 insertions(+), 27 deletions(-) diff --git a/code/API_definitions/qos-profiles.yaml b/code/API_definitions/qos-profiles.yaml index 6804c7c5d4..d8676b443d 100644 --- a/code/API_definitions/qos-profiles.yaml +++ b/code/API_definitions/qos-profiles.yaml @@ -24,13 +24,41 @@ info: 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 device from the access token + + This specification defines the `device` object field as optional in API requests, specifically in cases where the API is accessed using a 3-legged access token, and the device can be uniquely identified by the token. This approach simplifies API usage for API consumers by relying on the device information associated with the access token used to invoke the API. + + ## Handling of device information: + + ### Optional device object for 3-legged tokens: + + - When using a 3-legged access token, the device associated with the access token must be considered as the device for the API request. This means that the device object is not required in the request, and if included it must identify the same device, 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 device identification from the access token, if available. + - If the API request additionally includes a `device` object when using a 3-legged access token, the API will validate that the device identifier 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 device information in the request does not match the token. + + ### Error handling for unidentifiable devices: + + - If the `device` object is not included in the request and the device information cannot be derived from the 3-legged access token, the server will return a 422 `UNIDENTIFIABLE_DEVICE` error. + + ### Restrictions for tokens without an associated authenticated identifier: + + - For scenarios which do not have a single device identifier associated to the token during the authentication flow, e.g. 2-legged access tokens, the `device` object MUST be provided in the API request. This ensures that the device identification is explicit and valid for each API call made with these tokens. + # Further info and support (FAQs will be added in a later version of the documentation) + + version: wip + license: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0.html - version: wip + + x-camara-commonalities: 0.4.0 externalDocs: description: Product documentation at Camara @@ -95,7 +123,7 @@ paths: "404": $ref: "#/components/responses/QosProfilesNotFound404" "500": - $ref: "#/components/responses/QoSProfile500" + $ref: "#/components/responses/Generic500" "503": $ref: "#/components/responses/Generic503" @@ -140,7 +168,7 @@ paths: "404": $ref: "#/components/responses/QosProfileNotFound404" "500": - $ref: "#/components/responses/QoSProfile500" + $ref: "#/components/responses/Generic500" "503": $ref: "#/components/responses/Generic503" @@ -399,46 +427,73 @@ components: responses: Generic400: - description: Invalid input + description: Bad Request headers: x-correlator: - $ref: '#/components/headers/x-correlator' + $ref: "#/components/headers/x-correlator" content: application/json: schema: $ref: "#/components/schemas/ErrorInfo" - example: - status: 400 - code: INVALID_ARGUMENT - message: "Schema validation failed at ..." + 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. + GENERIC_400_OUT_OF_RANGE: + description: Out of Range. Specific Syntax Exception used when a given field has a pre-defined range or a invalid filter criteria combination is requested + value: + status: 400 + code: OUT_OF_RANGE + message: Client specified an invalid range. Generic401: description: Unauthorized headers: x-correlator: - $ref: '#/components/headers/x-correlator' + $ref: "#/components/headers/x-correlator" content: application/json: schema: $ref: "#/components/schemas/ErrorInfo" - example: - status: 401 - code: UNAUTHENTICATED - message: "Authorization failed: ..." + examples: + GENERIC_401_UNAUTHENTICATED: + description: Request cannot be authenticated + value: + status: 401 + code: UNAUTHENTICATED + message: Request not authenticated due to missing, invalid, or expired credentials. + GENERIC_401_AUTHENTICATION_REQUIRED: + description: New authentication is needed, authentication is no longer valid + value: + status: 401 + code: AUTHENTICATION_REQUIRED + message: New authentication is required. Generic403: description: Forbidden headers: x-correlator: - $ref: '#/components/headers/x-correlator' + $ref: "#/components/headers/x-correlator" content: application/json: schema: $ref: "#/components/schemas/ErrorInfo" - example: - status: 403 - code: PERMISSION_DENIED - message: "Operation not allowed: ..." + 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. + GENERIC_403_INVALID_TOKEN_CONTEXT: + description: Reflect some inconsistency between information in some field of the API and the related OAuth2 Token + value: + status: 403 + code: INVALID_TOKEN_CONTEXT + message: "{{field}} is not consistent with access token." QosProfilesNotFound404: description: Qos Profiles not found @@ -468,7 +523,59 @@ components: code: NOT_FOUND message: "QosProfile Id does not exist" - QoSProfile500: + Generic422: + description: Unprocessable Content + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + examples: + GENERIC_422_DEVICE_IDENTIFIERS_MISMATCH: + description: Inconsistency between device identifiers not pointing to the same device + value: + status: 422 + code: DEVICE_IDENTIFIERS_MISMATCH + message: Provided device identifiers are not consistent. + GENERIC_422_DEVICE_NOT_APPLICABLE: + description: Service is not available for the provided device + value: + status: 422 + code: DEVICE_NOT_APPLICABLE + message: The service is not available for the provided device. + GENERIC_422_UNIDENTIFIABLE_DEVICE: + description: Service is not available for the provided device + value: + status: 422 + code: UNIDENTIFIABLE_DEVICE + message: The device cannot be identified. + + Generic429: + description: Too Many Requests + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + examples: + GENERIC_429_QUOTA_EXCEEDED: + description: Request is rejected due to exceeding a business quota limit + value: + status: 429 + code: QUOTA_EXCEEDED + message: Either out of resource quota or reaching rate limiting. + GENERIC_429_TOO_MANY_REQUESTS: + description: API Server request limit is overpassed + value: + status: 429 + code: TOO_MANY_REQUESTS + message: Either out of resource quota or reaching rate limiting. + + Generic500: description: Internal server error headers: x-correlator: @@ -480,18 +587,21 @@ components: example: status: 500 code: INTERNAL - message: "Internal server error: Could not get QoS Profile" + message: "Internal server error: ..." Generic503: - description: Service unavailable + description: Service Unavailable headers: x-correlator: - $ref: '#/components/headers/x-correlator' + $ref: "#/components/headers/x-correlator" content: application/json: schema: $ref: "#/components/schemas/ErrorInfo" - example: - status: 503 - code: UNAVAILABLE - message: "Service unavailable" + examples: + GENERIC_503_UNAVAILABLE: + description: Service is not available. Temporary situation usually related to maintenance process in the server side + value: + status: 503 + code: UNAVAILABLE + message: Service Unavailable. From 126fcbdc70172ea68941961740ea60141196f3a9 Mon Sep 17 00:00:00 2001 From: Herbert Damker <52109189+hdamker@users.noreply.github.com> Date: Mon, 29 Jul 2024 20:21:34 +0200 Subject: [PATCH 13/27] Update qos-profiles.yaml Removing trailing spaces --- code/API_definitions/qos-profiles.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/code/API_definitions/qos-profiles.yaml b/code/API_definitions/qos-profiles.yaml index d8676b443d..e6b4fda5e3 100644 --- a/code/API_definitions/qos-profiles.yaml +++ b/code/API_definitions/qos-profiles.yaml @@ -57,7 +57,7 @@ info: license: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0.html - + x-camara-commonalities: 0.4.0 externalDocs: From 45e98bb5c33da60d690f2ccff864c288a3397b4d Mon Sep 17 00:00:00 2001 From: Herbert Damker Date: Wed, 31 Jul 2024 15:03:31 +0200 Subject: [PATCH 14/27] Update code/API_definitions/quality-on-demand.yaml Co-authored-by: Jose Luis Urien --- code/API_definitions/quality-on-demand.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/code/API_definitions/quality-on-demand.yaml b/code/API_definitions/quality-on-demand.yaml index 9bcf9280f9..357d77543c 100644 --- a/code/API_definitions/quality-on-demand.yaml +++ b/code/API_definitions/quality-on-demand.yaml @@ -532,7 +532,7 @@ components: Session related information returned in responses. Within the optional device object only one identifier will be returned (with the original value provided in CreateSession). If no device identifier was provided in CreateSession (together with a 3-legged token), no device object will be returned in SessionInfo. - Please note that IP addresses of devices can change and get reused and can't be used in these cases again to identify the same device. + Please note that IP addresses of devices can change and get reused, so the original values may no longer identify the same device. They identified the device at the time of session creation. allOf: - $ref: "#/components/schemas/BaseSessionInfo" - type: object From 061776de7e60d68b91967e815413adc88e37651b Mon Sep 17 00:00:00 2001 From: Herbert Damker <52109189+hdamker@users.noreply.github.com> Date: Thu, 1 Aug 2024 16:23:13 +0200 Subject: [PATCH 15/27] Update quality-on-demand.yaml Replaced specific examples by Generic400 Copied example "DurationOutOfRandForQoSProfile" into Generic400 --- code/API_definitions/quality-on-demand.yaml | 58 +++------------------ 1 file changed, 7 insertions(+), 51 deletions(-) diff --git a/code/API_definitions/quality-on-demand.yaml b/code/API_definitions/quality-on-demand.yaml index 357d77543c..160d1b9599 100644 --- a/code/API_definitions/quality-on-demand.yaml +++ b/code/API_definitions/quality-on-demand.yaml @@ -204,57 +204,7 @@ paths: schema: $ref: "#/components/schemas/SessionInfo" "400": - description: Invalid input for createSession operation - headers: - x-correlator: - $ref: '#/components/headers/x-correlator' - content: - application/json: - schema: - $ref: "#/components/schemas/ErrorInfo" - examples: - Generic400: - summary: Some parameter combinations or parameter values provided are not schema compliant - value: - status: 400 - code: INVALID_ARGUMENT - message: "Schema validation failed at ..." - DeviceMissing: - summary: Device must be specified - value: - status: 400 - code: INVALID_ARGUMENT - message: "Expected property is missing: device" - InvalidDevicePublicPortValue: - summary: Invalid port specified for device public port - value: - status: 400 - code: OUT_OF_RANGE - message: "Invalid port value specified: device.ipv4Address.publicPort" - ApplicationServerMissing: - summary: Application server must be specified - value: - status: 400 - code: INVALID_ARGUMENT - message: "Expected property is missing: applicationServer" - QoSProfileMissing: - summary: Required QoS profile must be specified - value: - status: 400 - code: INVALID_ARGUMENT - message: "Expected property is missing: qosProfile" - InvalidDevicePortsRanges: - summary: Invalid port ranges specified for devicePorts - value: - status: 400 - code: OUT_OF_RANGE - message: "Invalid port ranges specified: devicePorts" - DurationOutOfRangeForQoSProfile: - summary: The requested duration is out of the allowed range for the specific QoS profile - value: - status: 400 - code: OUT_OF_RANGE - message: "The requested duration is out of the allowed range for the specific QoS profile" + $ref: "#/components/responses/Generic400" "401": $ref: "#/components/responses/Generic401" "403": @@ -914,6 +864,12 @@ components: status: 400 code: OUT_OF_RANGE message: Client specified an invalid range. + DurationOutOfRangeForQoSProfile: + summary: The requested duration is out of the allowed range for the specific QoS profile + value: + status: 400 + code: OUT_OF_RANGE + message: "The requested duration is out of the allowed range for the specific QoS profile" Generic401: description: Unauthorized From e4941dabba334937bc083d2d6455a3aa55e6c117 Mon Sep 17 00:00:00 2001 From: Herbert Damker <52109189+hdamker@users.noreply.github.com> Date: Thu, 1 Aug 2024 16:31:40 +0200 Subject: [PATCH 16/27] Update quality-on-demand.yaml Use of Generic400 for all endpoints --- code/API_definitions/quality-on-demand.yaml | 22 +-------------------- 1 file changed, 1 insertion(+), 21 deletions(-) diff --git a/code/API_definitions/quality-on-demand.yaml b/code/API_definitions/quality-on-demand.yaml index 160d1b9599..7066f2bdf3 100644 --- a/code/API_definitions/quality-on-demand.yaml +++ b/code/API_definitions/quality-on-demand.yaml @@ -373,27 +373,7 @@ paths: schema: $ref: "#/components/schemas/SessionInfo" "400": - description: Invalid input for extendQosSessionDuration operation - headers: - x-correlator: - $ref: '#/components/headers/x-correlator' - content: - application/json: - schema: - $ref: "#/components/schemas/ErrorInfo" - examples: - Generic400: - summary: Some parameter combinations or parameter values provided are not schema compliant - value: - status: 400 - code: INVALID_ARGUMENT - message: "Schema validation failed at ..." - InactiveSession: - summary: The target session is inactive - value: - status: 400 - code: INVALID_ARGUMENT - message: "The target session is inactive" + $ref: "#/components/responses/Generic400" "401": $ref: "#/components/responses/Generic401" "403": From 033602e7dab34a2fbdac874e1a4524e84a5a8909 Mon Sep 17 00:00:00 2001 From: Herbert Damker <52109189+hdamker@users.noreply.github.com> Date: Thu, 1 Aug 2024 17:49:35 +0200 Subject: [PATCH 17/27] Update qos-profiles.yaml Replaced QosProfilesNotFound404 with Generic404 from CAMARA_common --- code/API_definitions/qos-profiles.yaml | 41 +++++++++++--------------- 1 file changed, 18 insertions(+), 23 deletions(-) diff --git a/code/API_definitions/qos-profiles.yaml b/code/API_definitions/qos-profiles.yaml index e6b4fda5e3..616fa859b0 100644 --- a/code/API_definitions/qos-profiles.yaml +++ b/code/API_definitions/qos-profiles.yaml @@ -121,7 +121,7 @@ paths: "403": $ref: "#/components/responses/Generic403" "404": - $ref: "#/components/responses/QosProfilesNotFound404" + $ref: "#/components/responses/Generic404" "500": $ref: "#/components/responses/Generic500" "503": @@ -166,7 +166,7 @@ paths: "403": $ref: "#/components/responses/Generic403" "404": - $ref: "#/components/responses/QosProfileNotFound404" + $ref: "#/components/responses/Generic404" "500": $ref: "#/components/responses/Generic500" "503": @@ -495,33 +495,28 @@ components: code: INVALID_TOKEN_CONTEXT message: "{{field}} is not consistent with access token." - QosProfilesNotFound404: - description: Qos Profiles not found + Generic404: + description: Not found headers: x-correlator: - $ref: '#/components/headers/x-correlator' - content: - application/json: - schema: - $ref: "#/components/schemas/ErrorInfo" - example: - status: 404 - code: NOT_FOUND - message: "No QoS Profiles found" - - QosProfileNotFound404: - description: Qos Profile not found - headers: - x-correlator: - $ref: '#/components/headers/x-correlator' + $ref: "#/components/headers/x-correlator" content: application/json: schema: $ref: "#/components/schemas/ErrorInfo" - example: - status: 404 - code: NOT_FOUND - message: "QosProfile Id does not exist" + 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_DEVICE_NOT_FOUND: + description: Device identifier not found + value: + status: 404 + code: DEVICE_NOT_FOUND + message: Device identifier not found. Generic422: description: Unprocessable Content From 27a767294c8ae8b959bf67f26a795ea09c7fbd30 Mon Sep 17 00:00:00 2001 From: Herbert Damker <52109189+hdamker@users.noreply.github.com> Date: Thu, 1 Aug 2024 20:28:46 +0200 Subject: [PATCH 18/27] Update quality-on-demand.yaml Changed description of SessionInfo based on review comment. --- code/API_definitions/quality-on-demand.yaml | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/code/API_definitions/quality-on-demand.yaml b/code/API_definitions/quality-on-demand.yaml index 7066f2bdf3..818a388c0f 100644 --- a/code/API_definitions/quality-on-demand.yaml +++ b/code/API_definitions/quality-on-demand.yaml @@ -460,8 +460,7 @@ components: SessionInfo: description: | Session related information returned in responses. - Within the optional device object only one identifier will be returned (with the original value provided in CreateSession). - If no device identifier was provided in CreateSession (together with a 3-legged token), no device object will be returned in SessionInfo. + Optional device object only to be returned if provided in createSession. If more than one type of device identifier was provided, only one identifier will be returned (at implementation choice and with the original value provided in createSession). Please note that IP addresses of devices can change and get reused, so the original values may no longer identify the same device. They identified the device at the time of session creation. allOf: - $ref: "#/components/schemas/BaseSessionInfo" From 984e12bbd9488e19aab757c45aa0f8d639899acf Mon Sep 17 00:00:00 2001 From: Herbert Damker Date: Fri, 2 Aug 2024 06:40:41 +0200 Subject: [PATCH 19/27] Update code/API_definitions/quality-on-demand.yaml Co-authored-by: Jose Luis Urien --- code/API_definitions/quality-on-demand.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/code/API_definitions/quality-on-demand.yaml b/code/API_definitions/quality-on-demand.yaml index 818a388c0f..dbab2bef42 100644 --- a/code/API_definitions/quality-on-demand.yaml +++ b/code/API_definitions/quality-on-demand.yaml @@ -231,7 +231,7 @@ paths: **NOTES:** - The access token may be either 2-legged or 3-legged. - If a 3-legged access token is used, the end user (and device) associated with the session must also be associated with the access token. - - The session must must have been created by the same API client given in the access token + - The session must have been created by the same API client given in the access token operationId: getSession security: From 8d23c566514d2f87e82e4a1741046e7b329c2d63 Mon Sep 17 00:00:00 2001 From: Herbert Damker <52109189+hdamker@users.noreply.github.com> Date: Fri, 2 Aug 2024 06:45:11 +0200 Subject: [PATCH 20/27] Update quality-on-demand.yaml Applied review comment https://github.com/camaraproject/QualityOnDemand/pull/326#discussion_r1700701939 --- code/API_definitions/quality-on-demand.yaml | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/code/API_definitions/quality-on-demand.yaml b/code/API_definitions/quality-on-demand.yaml index dbab2bef42..ad4fb0a826 100644 --- a/code/API_definitions/quality-on-demand.yaml +++ b/code/API_definitions/quality-on-demand.yaml @@ -136,7 +136,9 @@ paths: - In case of a `QOS_STATUS_CHANGED` event with `qosStatus` as `UNAVAILABLE` and `statusInfo` as `NETWORK_TERMINATED` the resources of the QoS session are not directly released, but will get deleted automatically at earliest 360 seconds after the event. This behavior allows clients which are not receiving notification events but are polling to get the session information with the `qosStatus` `UNAVAILABLE` and `statusInfo` `NETWORK_TERMINATED`. Before a client can attempt to create a new QoD session for the same device and flow period they must release the session resources with an explicit `delete` operation if not yet automatically deleted. - - The access token may be either 2-legged or 3-legged. If a 3-legged access token which is associated with a device is used, it is recommended NOT to include the `device` parameter in the request (see "Handling of device information" within the API description for details). + - The access token may be either 2-legged or 3-legged. + - If a 3-legged access token which is associated with a device is used, it is recommended NOT to include the `device` parameter in the request (see "Handling of device information" within the API description for details). + - If a 2-legged access token is used, the device parameter must be provided and identify a device. operationId: createSession security: From d70cdd8397586dc1d1550d8b7609efd9ea34cbe9 Mon Sep 17 00:00:00 2001 From: Herbert Damker <52109189+hdamker@users.noreply.github.com> Date: Fri, 2 Aug 2024 06:48:12 +0200 Subject: [PATCH 21/27] Update quality-on-demand.yaml Removed trailing space --- code/API_definitions/quality-on-demand.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/code/API_definitions/quality-on-demand.yaml b/code/API_definitions/quality-on-demand.yaml index ad4fb0a826..088f664abd 100644 --- a/code/API_definitions/quality-on-demand.yaml +++ b/code/API_definitions/quality-on-demand.yaml @@ -136,7 +136,7 @@ paths: - In case of a `QOS_STATUS_CHANGED` event with `qosStatus` as `UNAVAILABLE` and `statusInfo` as `NETWORK_TERMINATED` the resources of the QoS session are not directly released, but will get deleted automatically at earliest 360 seconds after the event. This behavior allows clients which are not receiving notification events but are polling to get the session information with the `qosStatus` `UNAVAILABLE` and `statusInfo` `NETWORK_TERMINATED`. Before a client can attempt to create a new QoD session for the same device and flow period they must release the session resources with an explicit `delete` operation if not yet automatically deleted. - - The access token may be either 2-legged or 3-legged. + - The access token may be either 2-legged or 3-legged. - If a 3-legged access token which is associated with a device is used, it is recommended NOT to include the `device` parameter in the request (see "Handling of device information" within the API description for details). - If a 2-legged access token is used, the device parameter must be provided and identify a device. From 5c9bddea1a3487d98bd59f89c7492ea45bf0c4c6 Mon Sep 17 00:00:00 2001 From: Herbert Damker <52109189+hdamker@users.noreply.github.com> Date: Fri, 2 Aug 2024 06:58:43 +0200 Subject: [PATCH 22/27] Update quality-on-demand.yaml Defined specific error code QUALITY_ON_DEMAND.DURATION_OUT_OF_RANGE --- code/API_definitions/quality-on-demand.yaml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/code/API_definitions/quality-on-demand.yaml b/code/API_definitions/quality-on-demand.yaml index 088f664abd..b18410b092 100644 --- a/code/API_definitions/quality-on-demand.yaml +++ b/code/API_definitions/quality-on-demand.yaml @@ -846,11 +846,11 @@ components: code: OUT_OF_RANGE message: Client specified an invalid range. DurationOutOfRangeForQoSProfile: - summary: The requested duration is out of the allowed range for the specific QoS profile + description: The requested duration is out of the allowed range for the specific QoS profile value: status: 400 - code: OUT_OF_RANGE - message: "The requested duration is out of the allowed range for the specific QoS profile" + code: QUALITY_ON_DEMAND.DURATION_OUT_OF_RANGE + message: The requested duration is out of the allowed range for the specific QoS profile Generic401: description: Unauthorized From 1ed6e92a49d1a987f1be1718898744ce77f0c2a0 Mon Sep 17 00:00:00 2001 From: Herbert Damker <52109189+hdamker@users.noreply.github.com> Date: Fri, 2 Aug 2024 10:07:41 +0200 Subject: [PATCH 23/27] Update quality-on-demand.yaml Addressed review comments --- code/API_definitions/quality-on-demand.yaml | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/code/API_definitions/quality-on-demand.yaml b/code/API_definitions/quality-on-demand.yaml index b18410b092..7b233990b9 100644 --- a/code/API_definitions/quality-on-demand.yaml +++ b/code/API_definitions/quality-on-demand.yaml @@ -101,7 +101,7 @@ info: externalDocs: description: Product documentation at Camara - url: https://github.com/camaraproject/ + url: https://github.com/camaraproject/QualityOnDemand servers: - url: "{apiRoot}/quality-on-demand/vwip" @@ -211,6 +211,8 @@ paths: $ref: "#/components/responses/Generic401" "403": $ref: "#/components/responses/Generic403" + "404": + $ref: "#/components/responses/Generic404" "409": $ref: "#/components/responses/SessionInConflict409" "422": From 151abbae6ec829a5cb7af95963f3aaa37eb3f5e4 Mon Sep 17 00:00:00 2001 From: Herbert Damker <52109189+hdamker@users.noreply.github.com> Date: Fri, 2 Aug 2024 10:09:22 +0200 Subject: [PATCH 24/27] Update quality-on-demand.yaml Address review comment --- code/API_definitions/quality-on-demand.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/code/API_definitions/quality-on-demand.yaml b/code/API_definitions/quality-on-demand.yaml index 7b233990b9..87c3269404 100644 --- a/code/API_definitions/quality-on-demand.yaml +++ b/code/API_definitions/quality-on-demand.yaml @@ -100,7 +100,7 @@ info: x-camara-commonalities: 0.4.0 externalDocs: - description: Product documentation at Camara + description: Project documentation at Camara url: https://github.com/camaraproject/QualityOnDemand servers: From eb013bd76e72146c3a0dc2bf96ea0c46183ed1b2 Mon Sep 17 00:00:00 2001 From: Herbert Damker <52109189+hdamker@users.noreply.github.com> Date: Fri, 2 Aug 2024 10:11:34 +0200 Subject: [PATCH 25/27] Update qos-profiles.yaml externalDocs updated --- code/API_definitions/qos-profiles.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/code/API_definitions/qos-profiles.yaml b/code/API_definitions/qos-profiles.yaml index 616fa859b0..b0fb161a46 100644 --- a/code/API_definitions/qos-profiles.yaml +++ b/code/API_definitions/qos-profiles.yaml @@ -61,8 +61,8 @@ info: x-camara-commonalities: 0.4.0 externalDocs: - description: Product documentation at Camara - url: https://github.com/camaraproject/ + description: Project documentation at Camara + url: https://github.com/camaraproject/QualityOnDemand servers: - url: "{apiRoot}/qos-profiles/vwip" From 55c609a4a07735654f6c6e985ccac92156fc584d Mon Sep 17 00:00:00 2001 From: Herbert Damker <52109189+hdamker@users.noreply.github.com> Date: Mon, 5 Aug 2024 08:50:15 +0200 Subject: [PATCH 26/27] Update quality-on-demand.yaml Added error schema "GenericDevice404" as discussed in https://github.com/camaraproject/QualityOnDemand/pull/326#issuecomment-2265157950 --- code/API_definitions/quality-on-demand.yaml | 19 ++++++++++++++++++- 1 file changed, 18 insertions(+), 1 deletion(-) diff --git a/code/API_definitions/quality-on-demand.yaml b/code/API_definitions/quality-on-demand.yaml index 87c3269404..d05c265779 100644 --- a/code/API_definitions/quality-on-demand.yaml +++ b/code/API_definitions/quality-on-demand.yaml @@ -212,7 +212,7 @@ paths: "403": $ref: "#/components/responses/Generic403" "404": - $ref: "#/components/responses/Generic404" + $ref: "#/components/responses/GenericDevice404" "409": $ref: "#/components/responses/SessionInConflict409" "422": @@ -901,6 +901,23 @@ components: message: "{{field}} is not consistent with access token." Generic404: + description: Not found + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + examples: + GENERIC_404_NOT_FOUND: + description: Resource is not found + value: + status: 404 + code: NOT_FOUND + message: The specified resource is not found. + + GenericDevice404: description: Not found headers: x-correlator: From 70ea70ee9386eebd4b7e102887021739cedb1385 Mon Sep 17 00:00:00 2001 From: Herbert Damker <52109189+hdamker@users.noreply.github.com> Date: Mon, 5 Aug 2024 16:36:58 +0200 Subject: [PATCH 27/27] Update quality-on-demand.yaml MNO replaced with network operator --- code/API_definitions/quality-on-demand.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/code/API_definitions/quality-on-demand.yaml b/code/API_definitions/quality-on-demand.yaml index d05c265779..87a0f84c8d 100644 --- a/code/API_definitions/quality-on-demand.yaml +++ b/code/API_definitions/quality-on-demand.yaml @@ -681,7 +681,7 @@ components: * `phoneNumber` * `networkAccessIdentifier` - NOTE1: the MNO might support only a subset of these options. The API invoker can provide multiple identifiers to be compatible across different MNOs. In this case the identifiers MUST belong to the same device + NOTE1: the network operator might support only a subset of these options. The API invoker can provide multiple identifiers to be compatible across different network operators. In this case the identifiers MUST belong to the same device NOTE2: for the Commonalities release v0.4, we are enforcing that the networkAccessIdentifier is only part of the schema for future-proofing, and CAMARA does not currently allow its use. After the CAMARA meta-release work is concluded and the relevant issues are resolved, its use will need to be explicitly documented in the guidelines. type: object properties: