Update device error model #232
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -22,6 +22,7 @@ info: | |
| - `5G`, if device is connected to the 5G network technology | ||
| - `UNKNOWN` if connection [technology] can not be determined | ||
|
|
||
|
|
||
| * **LastStatusTime** : This property specifies the time when the status was last updated. Its presence in the response indicates the freshness of the information, while its absence implies the information may be outdated or its freshness is uncertain. | ||
|
|
||
| # API Functionality | ||
|
|
@@ -32,29 +33,28 @@ info: | |
|
|
||
| The endpoint `POST /retrieve` allows to get connected Network Type. | ||
|
|
||
| # Identifying the device from the access token | ||
|
|
||
| This API requires the API consumer to identify a device 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 `device` object, 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 `device` object 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 `device` object 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. | ||
|
|
||
| # 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 provider of the application consuming the API and the operator's API exposure platform, 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. | ||
|
|
||
| ## Multi-SIM scenario handling | ||
|
|
||
| In multi-SIM scenarios where more than one mobile device is associated with a phone number (e.g. a smartphone with an associated smartwatch), it might not be possible to uniquely identify from that phone number the device for which the connected network type should be returned. If the phone number is used as the device identifier when querying in a multi-SIM scenario, the API may: | ||
|
|
@@ -67,6 +67,10 @@ info: | |
| - Identifying the intended device from a unique identifier for that device, such as its source IP address and port | ||
| - Check with the SIM provider whether a unique "secondary" phone number is already associated with each device, and use the secondary phone number to identify the intended device if available. | ||
|
|
||
| ## Further info and support | ||
|
|
||
| (FAQs will be added in a later version of the documentation) | ||
|
|
||
| termsOfService: http://swagger.io/terms/ | ||
| contact: | ||
| email: [email protected] | ||
|
|
@@ -136,15 +140,13 @@ paths: | |
| "401": | ||
| $ref: "#/components/responses/Generic401" | ||
| "403": | ||
| $ref: "#/components/responses/Generic403" | ||
| "404": | ||
| $ref: "#/components/responses/Generic404" | ||
| "422": | ||
| $ref: "#/components/responses/Generic422" | ||
| "429": | ||
| $ref: "#/components/responses/Generic429" | ||
| components: | ||
| securitySchemes: | ||
| openId: | ||
|
|
@@ -157,11 +159,15 @@ components: | |
| description: Correlation id for the different services | ||
| schema: | ||
| type: string | ||
| pattern: ^[a-zA-Z0-9-]{0,55}$ | ||
| example: "b4333c46-49c0-4f62-80d7-f0ef930f1c46" | ||
| headers: | ||
| x-correlator: | ||
| description: Correlation id for the different services | ||
| schema: | ||
| type: string | ||
| pattern: ^[a-zA-Z0-9-]{0,55}$ | ||
| example: "b4333c46-49c0-4f62-80d7-f0ef930f1c46" | ||
| schemas: | ||
| LastStatusTime: | ||
| description: Last time that the associated connected Network Type was updated | ||
|
|
@@ -298,142 +304,194 @@ components: | |
|
|
||
| responses: | ||
| Generic400: | ||
| description: Bad Request | ||
| headers: | ||
| x-correlator: | ||
| $ref: "#/components/headers/x-correlator" | ||
| content: | ||
| application/json: | ||
| schema: | ||
| allOf: | ||
| - $ref: "#/components/schemas/ErrorInfo" | ||
| - type: object | ||
| properties: | ||
| status: | ||
| enum: | ||
| - 400 | ||
| code: | ||
| enum: | ||
| - INVALID_ARGUMENT | ||
| 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. | ||
| Generic401: | ||
| description: Unauthorized | ||
| headers: | ||
| x-correlator: | ||
| $ref: "#/components/headers/x-correlator" | ||
| content: | ||
| application/json: | ||
| schema: | ||
| allOf: | ||
| - $ref: "#/components/schemas/ErrorInfo" | ||
| - type: object | ||
| properties: | ||
| status: | ||
| enum: | ||
| - 401 | ||
| code: | ||
| enum: | ||
| - UNAUTHENTICATED | ||
|
Collaborator
There was a problem hiding this comment. There is an open issue in Commonalities to discuss the future of
Collaborator
Author
There was a problem hiding this comment. I'm also happy with UNAUTHENTICATED |
||
| 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. | ||
| Generic403: | ||
| description: Forbidden | ||
| headers: | ||
| x-correlator: | ||
| $ref: "#/components/headers/x-correlator" | ||
| content: | ||
| application/json: | ||
| schema: | ||
| allOf: | ||
| - $ref: "#/components/schemas/ErrorInfo" | ||
| - type: object | ||
| properties: | ||
| status: | ||
| enum: | ||
| - 403 | ||
| code: | ||
| enum: | ||
| - PERMISSION_DENIED | ||
| 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. | ||
| Generic404: | ||
| description: Not found | ||
| headers: | ||
| x-correlator: | ||
| $ref: "#/components/headers/x-correlator" | ||
| content: | ||
| application/json: | ||
| schema: | ||
| allOf: | ||
| - $ref: "#/components/schemas/ErrorInfo" | ||
| - type: object | ||
| properties: | ||
| status: | ||
| enum: | ||
| - 404 | ||
| code: | ||
| enum: | ||
| - NOT_FOUND | ||
|
Collaborator
There was a problem hiding this comment. Do we have a use for
Collaborator
Author
There was a problem hiding this comment. mmm I don't think we have a use case. I agree to remove it.
Collaborator
There was a problem hiding this comment. I agree, we need only IDENTIFIER_NOT_FOUND |
||
| - IDENTIFIER_NOT_FOUND | ||
| 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_IDENTIFIER_NOT_FOUND: | ||
| description: The phone number is not associated with a CSP customer account | ||
| value: | ||
| status: 404 | ||
| code: IDENTIFIER_NOT_FOUND | ||
| message: The phone number provided is not associated with a customer account | ||
| Generic422: | ||
| description: Unprocessable Content | ||
| headers: | ||
| x-correlator: | ||
| $ref: "#/components/headers/x-correlator" | ||
| content: | ||
| application/json: | ||
| schema: | ||
| allOf: | ||
| - $ref: "#/components/schemas/ErrorInfo" | ||
| - type: object | ||
| properties: | ||
| status: | ||
| enum: | ||
| - 422 | ||
| code: | ||
| enum: | ||
| - IDENTIFIER_MISMATCH | ||
| - SERVICE_NOT_APPLICABLE | ||
| - MISSING_IDENTIFIER | ||
| - UNSUPPORTED_IDENTIFIER | ||
| - UNNECESSARY_IDENTIFIER | ||
| examples: | ||
| GENERIC_422_IDENTIFIER_MISMATCH: | ||
| description: Inconsistency between identifiers not pointing to the same device | ||
| value: | ||
| status: 422 | ||
| code: IDENTIFIER_MISMATCH | ||
| message: Provided identifiers are not consistent. | ||
| GENERIC_422_SERVICE_NOT_APPLICABLE: | ||
| description: Service not applicable for the provided identifier | ||
| value: | ||
| status: 422 | ||
| code: SERVICE_NOT_APPLICABLE | ||
| message: The service is not available for the provided identifier. | ||
| GENERIC_422_MISSING_IDENTIFIER: | ||
| description: An identifier is not included in the request and the device or phone number identification cannot be derived from the 3-legged access token | ||
| value: | ||
| status: 422 | ||
| code: MISSING_IDENTIFIER | ||
| message: The device cannot be identified. | ||
| GENERIC_422_UNSUPPORTED_IDENTIFIER: | ||
| description: None of the provided identifiers is supported by the implementation | ||
| value: | ||
| status: 422 | ||
| code: UNSUPPORTED_IDENTIFIER | ||
| message: The identifier provided is not supported. | ||
| GENERIC_422_UNNECESSARY_IDENTIFIER: | ||
| description: An explicit identifier is provided when a device or phone number has already been identified from the access token | ||
| value: | ||
| status: 422 | ||
| code: UNNECESSARY_IDENTIFIER | ||
| message: The device is already identified by the access token. | ||
| Generic429: | ||
| description: Too Many Requests | ||
| headers: | ||
| x-correlator: | ||
| $ref: "#/components/headers/x-correlator" | ||
| content: | ||
| application/json: | ||
| schema: | ||
| allOf: | ||
| - $ref: "#/components/schemas/ErrorInfo" | ||
| - type: object | ||
| properties: | ||
| status: | ||
| enum: | ||
| - 429 | ||
| code: | ||
| enum: | ||
| - QUOTA_EXCEEDED | ||
| - TOO_MANY_REQUESTS | ||
| examples: | ||
|
Collaborator
There was a problem hiding this comment. We have to align message fieldd and description for Error 429
Collaborator
Author
There was a problem hiding this comment. done, thanks! |
||
| GENERIC_429_QUOTA_EXCEEDED: | ||
| description: Request is rejected due to exceeding a business quota limit | ||
| value: | ||
| status: 429 | ||
| code: QUOTA_EXCEEDED | ||
| message: Out of resource quota. | ||
| GENERIC_429_TOO_MANY_REQUESTS: | ||
| description: Access to the API has been temporarily blocked due to rate or spike arrest limits being reached | ||
| value: | ||
| status: 429 | ||
| code: TOO_MANY_REQUESTS | ||
| message: Rate limit reached. | ||
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This API doesn't have 406 and 415 as the other 2. I think for consistency reason the responses should be same for all 3 APIs. I'm not sure if we need those though...
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think that the tendency is to remove unused errors, maybe what we have to do is delete them from the other two apis
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I agree. We should remove 415 and 406 from all APIs. Neither is required to be documented, and their use in these APIs is nothing out of the ordinary for those status codes, and not related to the use case.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Agree as well - we should remove 415 & 406.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Done