From 9e05bf91a1262033f4559e48a94d77c254c50e5f Mon Sep 17 00:00:00 2001 From: Kevin Smith Date: Wed, 18 Dec 2024 15:15:58 +0000 Subject: [PATCH] Updates to errors and identifiers, fixes #56 #57 #58 --- .../simple-edge-discovery.yaml | 492 ++++++++++++------ 1 file changed, 334 insertions(+), 158 deletions(-) diff --git a/code/API_definitions/simple-edge-discovery.yaml b/code/API_definitions/simple-edge-discovery.yaml index c4ff4c8..5fde201 100644 --- a/code/API_definitions/simple-edge-discovery.yaml +++ b/code/API_definitions/simple-edge-discovery.yaml @@ -68,7 +68,7 @@ info: * If you call the API from a device attached to the operator network, then you can attempt the request without passing device identifier(s) parameters - in the request header. If that returns a 422 `UNIDENTIFIABLE_DEVICE` + in the request header. If that returns a 422 `MISSING_IDENTIFIER` error then retry the request but this time include a device identifier. NOTE1: the network operator might support only a subset of these options. @@ -510,218 +510,394 @@ components: maximum: 65535 responses: - Generic401: - description: Unauthorized + Generic400: + description: Bad Request + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" content: application/json: schema: - $ref: "#/components/schemas/ErrorInfo" - 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. + allOf: + - $ref: "#/components/schemas/ErrorInfo" + - type: object + properties: + status: + enum: + - 400 + code: + enum: + - INVALID_ARGUMENT + - OUT_OF_RANGE + - "{{SPECIFIC_CODE}}" + 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. + GENERIC_400_{{SPECIFIC_CODE}}: + description: Specific Syntax Exception regarding a field that is relevant in the context of the API + value: + status: 400 + code: { { SPECIFIC_CODE } } + message: { { SPECIFIC_CODE_MESSAGE } } + Generic401: + description: Unauthorized headers: - x-correlator: - $ref: "#/components/headers/x-correlator" + 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 + - AUTHENTICATION_REQUIRED + 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" content: - application/json: - schema: - $ref: "#/components/schemas/ErrorInfo" - 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." + application/json: + schema: + allOf: + - $ref: "#/components/schemas/ErrorInfo" + - type: object + properties: + status: + enum: + - 403 + code: + enum: + - PERMISSION_DENIED + - INVALID_TOKEN_CONTEXT + - "{{SPECIFIC_CODE}}" + 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." + GENERIC_403_{{SPECIFIC_CODE}}: + description: Indicate a Business Logic condition that forbids a process not attached to a specific field in the context of the API + value: + status: 403 + code: { { SPECIFIC_CODE } } + message: { { SPECIFIC_CODE_MESSAGE } } + 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 + - IDENTIFIER_NOT_FOUND + - "{{SPECIFIC_CODE}}" + 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: Some identifier cannot be matched to a device + value: + status: 404 + code: IDENTIFIER_NOT_FOUND + message: Device identifier not found. + GENERIC_404_{{SPECIFIC_CODE}}: + description: Specific situation to highlight the resource/concept not found + value: + status: 404 + code: { { SPECIFIC_CODE } } + message: { { SPECIFIC_CODE_MESSAGE } } + Generic406: + description: Not Acceptable headers: x-correlator: $ref: "#/components/headers/x-correlator" - Generic404: - description: Not found 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. - GENERIC_404_DEVICE_NOT_FOUND: - description: Device identifier not found - value: - status: 404 - code: DEVICE_NOT_FOUND - message: Device identifier not found. + allOf: + - $ref: "#/components/schemas/ErrorInfo" + - type: object + properties: + status: + enum: + - 406 + code: + enum: + - NOT_ACCEPTABLE + 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. + Generic410: + description: Gone headers: x-correlator: $ref: "#/components/headers/x-correlator" - Generic406: - description: Not Acceptable content: application/json: schema: - $ref: "#/components/schemas/ErrorInfo" + allOf: + - $ref: "#/components/schemas/ErrorInfo" + - type: object + properties: + status: + enum: + - 410 + code: + enum: + - GONE examples: - GENERIC_406_NOT_ACCEPTABLE: - description: | - API Server does not accept the media type (`Accept-*` header) indicated by API client + GENERIC_410_GONE: + description: Use in notifications flow to allow API Consumer to indicate that its callback is no longer available value: - status: 406 - code: NOT_ACCEPTABLE - message: | - The server cannot produce a response matching the content requested by the client - through `Accept-*` headers. - headers: - x-correlator: - $ref: "#/components/headers/x-correlator" + status: 410 + code: GONE + message: Access to the target resource is no longer available. 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: + GENERIC_422_IDENTIFIER_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 + 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: DEVICE_NOT_APPLICABLE - message: The Service is not available for the provided device. - GENERIC_422_UNIDENTIFIABLE_DEVICE: - description: The device identifier is not included in the request and the device information cannot be derived from the 3-legged access token + 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 identificationinformation cannot be derived from the 3-legged access token value: status: 422 - code: UNIDENTIFIABLE_DEVICE + code: MISSING_IDENTIFIER message: The device cannot be identified. - headers: - x-correlator: - $ref: "#/components/headers/x-correlator" + 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 - 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. headers: - x-correlator: - $ref: "#/components/headers/x-correlator" + 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: + 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 - content: - application/json: - schema: - $ref: "#/components/schemas/ErrorInfo" - 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. headers: - x-correlator: - $ref: "#/components/headers/x-correlator" + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + allOf: + - $ref: "#/components/schemas/ErrorInfo" + - type: object + properties: + status: + enum: + - 500 + code: + enum: + - INTERNAL + 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 - 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. headers: x-correlator: $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + allOf: + - $ref: "#/components/schemas/ErrorInfo" + - type: object + properties: + status: + enum: + - 501 + code: + enum: + - NOT_IMPLEMENTED + 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 - 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. - headers: - x-correlator: - $ref: "#/components/headers/x-correlator" + description: Bad Gateway + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + allOf: + - $ref: "#/components/schemas/ErrorInfo" + - type: object + properties: + status: + enum: + - 502 + code: + enum: + - BAD_GATEWAY + 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 - content: - application/json: - schema: - $ref: "#/components/schemas/ErrorInfo" - 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. headers: x-correlator: $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + allOf: + - $ref: "#/components/schemas/ErrorInfo" + - type: object + properties: + status: + enum: + - 503 + code: + enum: + - 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 - 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. headers: x-correlator: $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + allOf: + - $ref: "#/components/schemas/ErrorInfo" + - type: object + properties: + status: + enum: + - 504 + code: + enum: + - TIMEOUT + examples: + GENERIC_504_TIMEOUT: + description: API Server Timeout + value: + status: 504 + code: TIMEOUT + message: Request timeout exceeded.