diff --git a/code/API_definitions/device-reachability-status.yaml b/code/API_definitions/device-reachability-status.yaml index bf891285..b92f5431 100644 --- a/code/API_definitions/device-reachability-status.yaml +++ b/code/API_definitions/device-reachability-status.yaml @@ -109,15 +109,29 @@ paths: "401": $ref: "#/components/responses/Generic401" "403": - $ref: "#/components/responses/ReachabilityPermissionDenied403" + $ref: "#/components/responses/Generic403" "404": - $ref: "#/components/responses/ReachabilityNotFound404" + $ref: "#/components/responses/Generic404" + "405": + $ref: "#/components/responses/Generic405" + "406": + $ref: "#/components/responses/Generic406" + "415": + $ref: "#/components/responses/Generic415" "422": - $ref: "#/components/responses/ReachabilityUnprocessableEntity422" + $ref: "#/components/responses/Generic422" + "429": + $ref: "#/components/responses/Generic429" "500": $ref: "#/components/responses/Generic500" + "501": + $ref: "#/components/responses/Generic501" + "502": + $ref: "#/components/responses/Generic502" "503": $ref: "#/components/responses/Generic503" + "504": + $ref: "#/components/responses/Generic504" components: securitySchemes: openId: @@ -276,11 +290,14 @@ components: schema: $ref: "#/components/schemas/ErrorInfo" example: - status: 400 - code: "INVALID_ARGUMENT" - message: "Client specified an invalid argument, request body or query param" + 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: Authentication problem with the client request + description: Unauthorized headers: x-correlator: $ref: '#/components/headers/x-correlator' @@ -289,10 +306,19 @@ components: schema: $ref: "#/components/schemas/ErrorInfo" example: - status: 401 - code: "UNAUTHENTICATED" - message: "Request not authenticated due to missing, invalid, or expired credentials" - ReachabilityPermissionDenied403: + 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: | Client does not have sufficient permission. In addition to regular scenario of `PERMISSION_DENIED`, other scenarios may exist: @@ -307,17 +333,19 @@ components: schema: $ref: '#/components/schemas/ErrorInfo' examples: - PermissionDenied: + 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" - InvalidTokenContext: + 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: Invalid access token context - ReachabilityNotFound404: + message: "{{field}} is not consistent with access token." + Generic404: description: Resource Not Found headers: x-correlator: @@ -327,25 +355,65 @@ components: schema: $ref: "#/components/schemas/ErrorInfo" examples: - DeviceIdentifierNotFound: + NOT_FOUND: + value: + status: 404 + code: NOT_FOUND + message: The specified resource is not found + DEVICE_IDENTIFIER_NOT_FOUND: value: status: 404 code: DEVICE_NOT_FOUND message: Some identifier cannot be matched to a device - Generic409: - description: Conflict + Generic405: + description: Method Not Allowed headers: x-correlator: - $ref: '#/components/headers/x-correlator' + $ref: "#/components/headers/x-correlator" content: application/json: schema: $ref: "#/components/schemas/ErrorInfo" - example: - status: 409 - code: CONFLICT - message: "The specified resource is in a conflict" - ReachabilityUnprocessableEntity422: + examples: + GENERIC_405_METHOD_NOT_ALLOWED: + description: Invalid HTTP verb used with a given endpoint + value: + status: 405 + code: METHOD_NOT_ALLOWED + message: The requested method is not allowed/supported on the target resource. + Generic406: + description: Not Acceptable + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + examples: + GENERIC_406_NOT_ACCEPTABLE: + description: API Server does not accept the media type (`Accept-*` header) indicated by API client + value: + status: 406 + code: NOT_ACCEPTABLE + message: The server cannot produce a response matching the content requested by the client through `Accept-*` headers. + Generic415: + description: Unsupported Media Type + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + examples: + GENERIC_415_UNSUPPORTED_MEDIA_TYPE: + description: Payload format of the request is in an unsupported format by the Server. Should not happen + value: + status: 415 + code: UNSUPPORTED_MEDIA_TYPE + message: The server refuses to accept the request because the payload format is in an unsupported format. + Generic422: description: Unprocessable Entity headers: x-correlator: @@ -355,49 +423,122 @@ components: schema: $ref: "#/components/schemas/ErrorInfo" examples: - UnsupportedDeviceIdentifiers: - value: - status: 422 - code: UNSUPPORTED_DEVICE_IDENTIFIERS - message: "None of the provided device identifiers is supported by the implementation" - InconsistentDeviceIdentifiers: + GENERIC_422_DEVICE_IDENTIFIERS_MISMATCH: + description: Inconsistency between device identifiers not pointing to the same device value: status: 422 code: DEVICE_IDENTIFIERS_MISMATCH - message: Device identifiers mismatch - DeviceNotSupported: + 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: Service not applicable to the device - NetworkIssueToRetrieveReacabilityStatus: + message: The service is not available for the provided device. + GENERIC_422_UNABLE_TO_PROVIDE_REACHABILITY_STATUS: value: status: 422 - code: DEVICE_REACHABILITY_STATUS.UNABLE_TO_PROVIDE_REACHABILITY_STATUS + code: UNABLE_TO_PROVIDE_REACHABILITY_STATUS message: Network issue - Unable to provide reachability status + 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: Server error + description: Internal Server Error headers: x-correlator: - $ref: '#/components/headers/x-correlator' + $ref: "#/components/headers/x-correlator" content: application/json: schema: $ref: "#/components/schemas/ErrorInfo" - example: - status: 500 - code: "INTERNAL" - message: "Server error" + examples: + GENERIC_500_INTERNAL: + description: Problem in Server side. Regular Server Exception + value: + status: 500 + code: INTERNAL + message: Unknown server error. Typically a server bug. + 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. + Generic502: + description: Bad Gateway + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + examples: + GENERIC_502_BAD_GATEWAY: + description: Internal routing problem in the Server side that blocks to manage the service properly + value: + status: 502 + code: BAD_GATEWAY + message: An upstream internal service cannot be reached. Generic503: - description: Service unavailable. Typically the server is down. + 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. + Generic504: + description: Gateway Timeout + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + examples: + GENERIC_504_TIMEOUT: + description: API Server Timeout + value: + status: 504 + code: TIMEOUT + message: Request timeout exceeded. diff --git a/code/API_definitions/device-roaming-status.yaml b/code/API_definitions/device-roaming-status.yaml index 4a9500cd..b7dd0884 100644 --- a/code/API_definitions/device-roaming-status.yaml +++ b/code/API_definitions/device-roaming-status.yaml @@ -124,9 +124,9 @@ paths: "401": $ref: "#/components/responses/Generic401" "403": - $ref: "#/components/responses/RoamingPermissionDenied403" + $ref: "#/components/responses/Generic403" "404": - $ref: "#/components/responses/RoamingNotFound404" + $ref: "#/components/responses/Generic404" "405": $ref: "#/components/responses/Generic405" "406": @@ -342,11 +342,11 @@ components: status: 401 code: AUTHENTICATION_REQUIRED message: New authentication is required. - RoamingPermissionDenied403: + Generic403: description: | Client does not have sufficient permission. In addition to regular scenario of `PERMISSION_DENIED`, other scenarios may exist: - - Phone number cannot be deducted from access token context.(`{"code": "DEVICE_ROAMING_STATUS.INVALID_TOKEN_CONTEXT","message": "Phone number cannot be deducted from access token context"}`) + - Phone number cannot be deducted from access token context.(`{"code": "3INVALID_TOKEN_CONTEXT","message": "Phone number cannot be deducted from access token context"}`) headers: X-Correlator: description: Correlation id for the different services @@ -369,7 +369,7 @@ components: status: 403 code: INVALID_TOKEN_CONTEXT message: "{{field}} is not consistent with access token." - RoamingNotFound404: + Generic404: description: Resource Not Found headers: x-correlator: