From 2071c5ed52b7398d65ca5aed275b9b5b010a7617 Mon Sep 17 00:00:00 2001 From: Kevin Smith Date: Mon, 16 Dec 2024 15:56:42 +0000 Subject: [PATCH 01/22] Update x-camara-commonalities version Fixes #52 --- code/API_definitions/simple-edge-discovery.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/code/API_definitions/simple-edge-discovery.yaml b/code/API_definitions/simple-edge-discovery.yaml index 78c0b5a..619fe06 100644 --- a/code/API_definitions/simple-edge-discovery.yaml +++ b/code/API_definitions/simple-edge-discovery.yaml @@ -3,7 +3,7 @@ openapi: 3.0.3 info: title: Simple Edge Discovery version: wip - x-camara-commonalities: 0.4.0 + x-camara-commonalities: 0.5.0 description: | # Find the closest Edge Cloud Zone --- From 8fc6970d1c4f167ee3452c340175dcd5e1faa07c Mon Sep 17 00:00:00 2001 From: Kevin Smith Date: Mon, 16 Dec 2024 16:26:37 +0000 Subject: [PATCH 02/22] Updated URL to vwip --- code/API_definitions/simple-edge-discovery.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/code/API_definitions/simple-edge-discovery.yaml b/code/API_definitions/simple-edge-discovery.yaml index 619fe06..20201db 100644 --- a/code/API_definitions/simple-edge-discovery.yaml +++ b/code/API_definitions/simple-edge-discovery.yaml @@ -254,7 +254,7 @@ externalDocs: url: https://github.com/camaraproject/EdgeCloud servers: - - url: "{apiRoot}/simple-edge-discovery/v1" + - url: "{apiRoot}/simple-edge-discovery/vwip" variables: apiRoot: default: https://localhost:9091 From 16a11f6fd8af065cbaa43d40cac0568e2ed32755 Mon Sep 17 00:00:00 2001 From: Kevin Smith Date: Mon, 16 Dec 2024 16:49:27 +0000 Subject: [PATCH 03/22] Updated securitySchemes, Fixes #55 --- code/API_definitions/simple-edge-discovery.yaml | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/code/API_definitions/simple-edge-discovery.yaml b/code/API_definitions/simple-edge-discovery.yaml index 20201db..595b001 100644 --- a/code/API_definitions/simple-edge-discovery.yaml +++ b/code/API_definitions/simple-edge-discovery.yaml @@ -407,11 +407,10 @@ paths: device identified in the request. components: - securitySchemes: - openId: - description: OpenID Provider Configuration Information. - type: openIdConnect - openIdConnectUrl: .well-known/openid-configuration + securitySchemes: + openId: + type: openIdConnect + openIdConnectUrl: https://example.com/.well-known/openid-configuration headers: x-correlator: From add7e01a6bb6b7c5857874c5c1fa3e3ede355d2a Mon Sep 17 00:00:00 2001 From: Kevin Smith Date: Mon, 16 Dec 2024 16:53:51 +0000 Subject: [PATCH 04/22] Indentation fix --- code/API_definitions/simple-edge-discovery.yaml | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/code/API_definitions/simple-edge-discovery.yaml b/code/API_definitions/simple-edge-discovery.yaml index 595b001..066bbcc 100644 --- a/code/API_definitions/simple-edge-discovery.yaml +++ b/code/API_definitions/simple-edge-discovery.yaml @@ -407,10 +407,10 @@ paths: device identified in the request. components: - securitySchemes: - openId: - type: openIdConnect - openIdConnectUrl: https://example.com/.well-known/openid-configuration + securitySchemes: + openId: + type: openIdConnect + openIdConnectUrl: https://example.com/.well-known/openid-configuration headers: x-correlator: From 4115919f193efebe95e21504837e406056b7a581 Mon Sep 17 00:00:00 2001 From: Kevin Smith Date: Tue, 17 Dec 2024 11:07:34 +0000 Subject: [PATCH 05/22] Update device identification, fixes #60 Fixes #60 --- .../simple-edge-discovery.yaml | 62 +++++++------------ 1 file changed, 22 insertions(+), 40 deletions(-) diff --git a/code/API_definitions/simple-edge-discovery.yaml b/code/API_definitions/simple-edge-discovery.yaml index 066bbcc..72e5c65 100644 --- a/code/API_definitions/simple-edge-discovery.yaml +++ b/code/API_definitions/simple-edge-discovery.yaml @@ -49,8 +49,8 @@ info: The API returns the closest Edge Cloud Zone to a given device, so that device needs to be identifiable by the network. This can be achieved either - by passing a device identifier in the request header, or, from the 3-legged - access token where implemented by the operator. + by passing a device identifier in the request header, or, from the + three-legged access token where implemented by the operator. ## Passing a device identifier in the request header @@ -112,50 +112,32 @@ info: Accept: application/json ``` - ## Identifying a device from the access token + ## Identifying the device from the access token - This specification defines the `device` identifying headers 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. + This API requires the API consumer to identify a device as the subject of + the API as follows: - ### Handling of device information: + - When the API is invoked using a two-legged access token, the subject will be + identified from the optional [`device` object | `phoneNumber` field](*), which + therefore MUST be provided. + - When a three-legged access token is used however, this optional identifier + MUST NOT be provided, as the subject will be uniquely identified from the access + token. - #### Optional device identifying headers for 3-legged tokens: + 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. - - 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 - a device identifying header 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. + ## Error handling: - #### Validation mechanism: + - 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. - - The server will extract the device identification from the access token, if - available. - - If the API request additionally includes a `device` identifying header - 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` identifying header is not included in the request and the - device information cannot be derived from the 3-legged access token, nor - inferred by the operator if the request is made directly from the client, - 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, a - `device` identifying header 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. + - 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. # Responses From fef6b371657d17129bd95aa1d94152ef01c88c8b Mon Sep 17 00:00:00 2001 From: Kevin Smith Date: Tue, 17 Dec 2024 11:13:00 +0000 Subject: [PATCH 06/22] Trimmed trailing spaces --- code/API_definitions/simple-edge-discovery.yaml | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/code/API_definitions/simple-edge-discovery.yaml b/code/API_definitions/simple-edge-discovery.yaml index 72e5c65..c4ff4c8 100644 --- a/code/API_definitions/simple-edge-discovery.yaml +++ b/code/API_definitions/simple-edge-discovery.yaml @@ -49,7 +49,7 @@ info: The API returns the closest Edge Cloud Zone to a given device, so that device needs to be identifiable by the network. This can be achieved either - by passing a device identifier in the request header, or, from the + by passing a device identifier in the request header, or, from the three-legged access token where implemented by the operator. ## Passing a device identifier in the request header @@ -114,13 +114,13 @@ info: ## Identifying the device from the access token - This API requires the API consumer to identify a device as the subject of + 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 | `phoneNumber` field](*), which therefore MUST be provided. - - When a three-legged access token is used however, this optional identifier + - 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. @@ -131,7 +131,7 @@ info: ## 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 + 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` From 9e05bf91a1262033f4559e48a94d77c254c50e5f Mon Sep 17 00:00:00 2001 From: Kevin Smith Date: Wed, 18 Dec 2024 15:15:58 +0000 Subject: [PATCH 07/22] 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. From 4157c30e781bf7d093c5cbe57141534b3f79aebc Mon Sep 17 00:00:00 2001 From: Kevin Smith Date: Wed, 18 Dec 2024 15:31:29 +0000 Subject: [PATCH 08/22] spacing fixes, removed unnecessary error boilerplate --- .../simple-edge-discovery.yaml | 346 ++++++++---------- 1 file changed, 160 insertions(+), 186 deletions(-) diff --git a/code/API_definitions/simple-edge-discovery.yaml b/code/API_definitions/simple-edge-discovery.yaml index 5fde201..ca62a5f 100644 --- a/code/API_definitions/simple-edge-discovery.yaml +++ b/code/API_definitions/simple-edge-discovery.yaml @@ -529,7 +529,6 @@ components: enum: - INVALID_ARGUMENT - OUT_OF_RANGE - - "{{SPECIFIC_CODE}}" examples: GENERIC_400_INVALID_ARGUMENT: description: Invalid Argument. Generic Syntax Exception @@ -543,122 +542,102 @@ components: 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. + 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" + 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 - - 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 } } + application/json: + schema: + allOf: + - $ref: "#/components/schemas/ErrorInfo" + - type: object + properties: + status: + enum: + - 403 + code: + enum: + - PERMISSION_DENIED + - INVALID_TOKEN_CONTEXT + 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." Generic404: description: Not found 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: - - 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 } } + application/json: + schema: + allOf: + - $ref: "#/components/schemas/ErrorInfo" + - type: object + properties: + status: + enum: + - 404 + code: + enum: + - 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: Some identifier cannot be matched to a device + value: + status: 404 + code: IDENTIFIER_NOT_FOUND + message: Device identifier not found. Generic406: description: Not Acceptable headers: @@ -713,7 +692,7 @@ components: description: Unprocessable Content headers: x-correlator: - $ref: "#/components/headers/x-correlator" + $ref: "#/components/headers/x-correlator" content: application/json: schema: @@ -726,81 +705,76 @@ components: code: IDENTIFIER_MISMATCH message: Provided identifiers are not consistent. GENERIC_422_SERVICE_NOT_APPLICABLE: - description: Service not applicable for the provided identifier + description: Service is not available for the provided device value: status: 422 code: SERVICE_NOT_APPLICABLE - message: The service is not available for the provided identifier. + message: The Service is not available for the provided device. GENERIC_422_MISSING_IDENTIFIER: - description: An identifier is not included in the request and the device or phone + 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: MISSING_IDENTIFIER message: The device cannot be identified. - 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" + 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. + 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 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. + 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 headers: @@ -827,30 +801,30 @@ components: 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: - allOf: - - $ref: "#/components/schemas/ErrorInfo" - - type: object - properties: - status: + 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: - - 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. + 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 headers: From b1e8ce2f3527a7e989125ec99f5b51f4050276e7 Mon Sep 17 00:00:00 2001 From: Kevin Smith Date: Wed, 18 Dec 2024 15:42:29 +0000 Subject: [PATCH 09/22] Another indentation fix --- .../simple-edge-discovery.yaml | 26 +++++++++---------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/code/API_definitions/simple-edge-discovery.yaml b/code/API_definitions/simple-edge-discovery.yaml index ca62a5f..6c4d165 100644 --- a/code/API_definitions/simple-edge-discovery.yaml +++ b/code/API_definitions/simple-edge-discovery.yaml @@ -529,19 +529,19 @@ components: enum: - INVALID_ARGUMENT - OUT_OF_RANGE - 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. + 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: From 90d6abfdf42ab0c52c88d1ad744d5222e0226389 Mon Sep 17 00:00:00 2001 From: Kevin Smith Date: Wed, 18 Dec 2024 15:51:49 +0000 Subject: [PATCH 10/22] More indentation fixes... --- .../simple-edge-discovery.yaml | 108 +++++++++--------- 1 file changed, 54 insertions(+), 54 deletions(-) diff --git a/code/API_definitions/simple-edge-discovery.yaml b/code/API_definitions/simple-edge-discovery.yaml index 6c4d165..e50cecd 100644 --- a/code/API_definitions/simple-edge-discovery.yaml +++ b/code/API_definitions/simple-edge-discovery.yaml @@ -656,13 +656,13 @@ components: 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. + 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: @@ -780,26 +780,26 @@ components: 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. + 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 headers: @@ -818,38 +818,38 @@ components: 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. + 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 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. + 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 headers: From 1ffebfb6d3877dc45cdf6f402d5d5981e019e013 Mon Sep 17 00:00:00 2001 From: Kevin Smith Date: Wed, 18 Dec 2024 16:06:49 +0000 Subject: [PATCH 11/22] More indent fixes... --- code/API_definitions/simple-edge-discovery.yaml | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/code/API_definitions/simple-edge-discovery.yaml b/code/API_definitions/simple-edge-discovery.yaml index e50cecd..372b8e6 100644 --- a/code/API_definitions/simple-edge-discovery.yaml +++ b/code/API_definitions/simple-edge-discovery.yaml @@ -470,7 +470,8 @@ components: description: Friendly Code to describe the error PhoneNumber: - description: A public identifier addressing a telephone subscription. In + description: + A public identifier addressing a telephone subscription. In mobile networks it corresponds to the MSISDN (Mobile Station International Subscriber Directory Number). In order to be globally unique it has to be formatted in international format, according to @@ -480,7 +481,8 @@ components: example: "+123456789" NetworkAccessIdentifier: - description: A public identifier addressing a subscription in a mobile + description: + A public identifier addressing a subscription in a mobile network. In 3GPP terminology, it corresponds to the GPSI formatted with the External Identifier ({Local Identifier}@{Domain Identifier}). Unlike the telephone number, the network access identifier is not From 7728bd26af3e10ee4c68b1153771113fef041193 Mon Sep 17 00:00:00 2001 From: Kevin Smith Date: Wed, 18 Dec 2024 16:13:11 +0000 Subject: [PATCH 12/22] Hopefully found the indent bug... --- code/API_definitions/simple-edge-discovery.yaml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/code/API_definitions/simple-edge-discovery.yaml b/code/API_definitions/simple-edge-discovery.yaml index 372b8e6..d7c9dba 100644 --- a/code/API_definitions/simple-edge-discovery.yaml +++ b/code/API_definitions/simple-edge-discovery.yaml @@ -655,9 +655,9 @@ components: status: enum: - 406 - code: - enum: - - NOT_ACCEPTABLE + code: + enum: + - NOT_ACCEPTABLE examples: GENERIC_406_NOT_ACCEPTABLE: description: API Server does not accept the media type (`Accept-*` header) indicated by API client From 06414852b12f3dc7f7784097a297538d57e1578d Mon Sep 17 00:00:00 2001 From: Kevin Smith Date: Wed, 18 Dec 2024 16:53:44 +0000 Subject: [PATCH 13/22] Fix indent errors --- .../simple-edge-discovery.yaml | 26 +++++++++---------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/code/API_definitions/simple-edge-discovery.yaml b/code/API_definitions/simple-edge-discovery.yaml index d7c9dba..c27530b 100644 --- a/code/API_definitions/simple-edge-discovery.yaml +++ b/code/API_definitions/simple-edge-discovery.yaml @@ -817,9 +817,9 @@ components: status: enum: - 502 - code: - enum: - - BAD_GATEWAY + code: + enum: + - BAD_GATEWAY examples: GENERIC_502_BAD_GATEWAY: description: Internal routing problem in the Server side that blocks to manage the service properly @@ -842,9 +842,9 @@ components: status: enum: - 503 - code: - enum: - - SERVICE_UNAVAILABLE + code: + enum: + - SERVICE_UNAVAILABLE examples: GENERIC_503_UNAVAILABLE: description: Service is not available. Temporary situation usually related to maintenance process in the server side @@ -870,10 +870,10 @@ components: code: enum: - TIMEOUT - examples: - GENERIC_504_TIMEOUT: - description: API Server Timeout - value: - status: 504 - code: TIMEOUT - message: Request timeout exceeded. + examples: + GENERIC_504_TIMEOUT: + description: API Server Timeout + value: + status: 504 + code: TIMEOUT + message: Request timeout exceeded. From 73dc2ee19e342c827018c08e76ab01f2333b4360 Mon Sep 17 00:00:00 2001 From: Kevin Smith Date: Wed, 18 Dec 2024 17:10:10 +0000 Subject: [PATCH 14/22] Fix Generic503 per Commonalities #362 --- code/API_definitions/simple-edge-discovery.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/code/API_definitions/simple-edge-discovery.yaml b/code/API_definitions/simple-edge-discovery.yaml index c27530b..312498b 100644 --- a/code/API_definitions/simple-edge-discovery.yaml +++ b/code/API_definitions/simple-edge-discovery.yaml @@ -850,7 +850,7 @@ components: description: Service is not available. Temporary situation usually related to maintenance process in the server side value: status: 503 - code: UNAVAILABLE + code: SERVICE_UNAVAILABLE message: Service Unavailable. Generic504: description: Gateway Timeout From ca41ab182845bf9b383d874a3efa43d33800e310 Mon Sep 17 00:00:00 2001 From: Kevin Smith Date: Wed, 18 Dec 2024 17:27:03 +0000 Subject: [PATCH 15/22] Generic503 code to UNAVAILBLE (Commonalities #359) --- code/API_definitions/simple-edge-discovery.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/code/API_definitions/simple-edge-discovery.yaml b/code/API_definitions/simple-edge-discovery.yaml index 312498b..e07ff88 100644 --- a/code/API_definitions/simple-edge-discovery.yaml +++ b/code/API_definitions/simple-edge-discovery.yaml @@ -844,13 +844,13 @@ components: - 503 code: enum: - - SERVICE_UNAVAILABLE + - 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: SERVICE_UNAVAILABLE + code: UNAVAILABLE message: Service Unavailable. Generic504: description: Gateway Timeout From b1f0b0ef1aa658368918c6ee2724102c37e6a410 Mon Sep 17 00:00:00 2001 From: Kevin Smith Date: Thu, 19 Dec 2024 11:42:51 +0000 Subject: [PATCH 16/22] Align test cases with new Errors, Fixes #59 --- .../simple-edge-discovery.feature | 40 +++++++++++-------- 1 file changed, 23 insertions(+), 17 deletions(-) diff --git a/code/Test_definitions/simple-edge-discovery.feature b/code/Test_definitions/simple-edge-discovery.feature index 12ead8a..391d5ea 100644 --- a/code/Test_definitions/simple-edge-discovery.feature +++ b/code/Test_definitions/simple-edge-discovery.feature @@ -15,43 +15,49 @@ Feature: CAMARA Simple Edge Discovery API - Operation readClosestEdgeCloudZone Then Response code is 200 OK And The response is an EdgeCloudZones object - @simple_edge_discovery_2_error_invalid_querystring + @simple_edge_discovery_2_error_out_of_range Scenario: Error because filter parameter is invalid Given the API Client makes a GET request to the {path_resource} - When The filter parameter is invalid - Then Response code is 400 INVALID_QUERYSTRING + When The filter parameter is not 'closest' + Then Response code is 400 OUT_OF_RANGE - @simple_edge_discovery_3_error_device_identifiers_not_supported - Scenario: Error because the device identifiers cannot be supported - Given the API Client makes a GET request to the {path_resource} - When The device identifier(s) are not supported by the implementation - Then Response code is 422 UNSUPPORTED_DEVICE_IDENTIFIERS - - @simple_edge_discovery_4_error_device_cannot_be_identified + @simple_edge_discovery_3_error_device_cannot_be_identified Scenario: Error because the device cannot be identified Given the API Client makes a GET request to the {path_resource} - When The device identifier(s) cannot be matched to a device - Then Response code is 422 UNIDENTIFIABLE_DEVICE + When The provided identifier(s) cannot be matched to a device + Then Response code is 404 IDENTIFIER_NOT_FOUND + + @simple_edge_discovery_4_error_identifiers_not_supported + Scenario: Error because the provided identifiers cannot be supported + Given the API Client makes a GET request to the {path_resource} + When The identifier(s) provided are not supported by the implementation + Then Response code is 422 UNSUPPORTED_IDENTIFIER @simple_edge_discovery_5_error_device_identifiers_mismatch Scenario: Error because provided device indentifiers are inconsistent Given the API Client makes a GET request to the {path_resource} When The provided device identifiers are not consistent - Then Response code is 422 DEVICE_IDENTIFIERS_MISMATCH + Then Response code is 422 IDENTIFIER_MISMATCH + + @simple_edge_discovery_6_error_missing_identifier + Scenario: Error because no identifier was provided + Given the API Client makes a GET request to the {path_resource} + When No identifier(s) are provided and cannot be derived from any 3-legged access token + Then Response code is 422 MISSING_IDENTIFIER - @simple_edge_discovery_6_error_invalid_access_token_context + @simple_edge_discovery_7_error_invalid_access_token_context Scenario: Error because access token context is invalid Given the API Client makes a GET request to the {path_resource} When The device identifiers are not consistent with access token Then Response code is 403 INVALID_TOKEN_CONTEXT - @simple_edge_discovery_7_error_service_not_applicable + @simple_edge_discovery_8_error_service_not_applicable Scenario: Error because the device is not connected to an edge-supporting network Given the API Client makes a GET request to the {path_resource} When The identified device is not connected to an edge-supporting network - Then Response code is 422 DEVICE_NOT_APPLICABLE + Then Response code is 422 SERVICE_NOT_APPLICABLE - @simple_edge_discovery_8_error_operator_cannot_resolve + @simple_edge_discovery_9_error_operator_cannot_resolve Scenario: Internal error at operator Given the API Client makes a GET request to the {path_resource} When The operator is unable to resolve due to internal error From e49606103e626ad8752b04c2e478dca4dcc17e5c Mon Sep 17 00:00:00 2001 From: Kevin Smith Date: Thu, 19 Dec 2024 14:57:23 +0000 Subject: [PATCH 17/22] Update simple-edge-discovery_API_Readiness_Checklist.md --- .../simple-edge-discovery_API_Readiness_Checklist.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/documentation/API_documentation/simple-edge-discovery_API_Readiness_Checklist.md b/documentation/API_documentation/simple-edge-discovery_API_Readiness_Checklist.md index c7df12b..652f0e4 100644 --- a/documentation/API_documentation/simple-edge-discovery_API_Readiness_Checklist.md +++ b/documentation/API_documentation/simple-edge-discovery_API_Readiness_Checklist.md @@ -1,6 +1,6 @@ # API Readiness Checklist -Checklist for simple-edge-discovery v1.0 in r1.3 +Checklist for simple-edge-discovery v1.1.0-alpha.1 | Nr | API release assets | alpha | release-candidate | initial
public | stable
public | Status | Comments | |----|----------------------------------------------|:-----:|:-----------------:|:-------:|:------:|:----:|:----:| @@ -15,6 +15,6 @@ Checklist for simple-edge-discovery v1.0 in r1.3 | 9 | Test result statement | O | O | O | M | N | Fall24 EXCEPTION: Test results not available (*) | | 10 | API release numbering convention applied | M | M | M | M | Y | | | 11 | Change log updated | M | M | M | M | Y | [link](/CHANGELOG.md) | -| 12 | Previous public release was certified | O | O | O | M | Y | [link](https://www.open-gateway.com) | +| 12 | Previous public release was certified | O | O | O | M | Y | see (1) | -(*) If you encounter issues with the provided test files (.feature), please create an issue in the API Sub-Project to signal these issues so they can be fixed in a patch release. +(1) Certified comapnies can be found at the [GSMA Open Gateway Portal](https://www.open-gateway.com) From 9dd864b4732f2bd97b2504431eaf4183287346d7 Mon Sep 17 00:00:00 2001 From: Kevin Smith Date: Thu, 19 Dec 2024 15:17:37 +0000 Subject: [PATCH 18/22] Update CHANGELOG.md --- CHANGELOG.md | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 3a1f7f1..921b924 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,7 @@ NOTE: ## Table of contents +- [v1.1.0-alpha.1](#v110---alpha1) - [r1.3](#r13) - [r1.2 - rc](#r12---rc) - [r1.1 - rc](#r11---rc) @@ -23,6 +24,26 @@ The below sections record the changes for each API version in each (pre-)release NOTE: SimpleEdgeDiscovery is part of the EdgeCloud API family, and was previously developed within the [EdgeCloud](https://github.com/camaraproject/EdgeCloud) repository. Two releases were made within EdgeCloud, v0.81 and r0.9.3-rc. These releases also include the other EdgeCloud APIs and materials, so the changelog below highlights only the changes related to SimpleEdgeDiscovery. Further information and links to the releases in EdgeCloud can be found below. +# v1.1.0-alpha.1 + +This alpha pre-release contains the definition and documentation of +* simple-edge-discovery v1.1.0-alpha.1 + +The API definition(s) are based on +* Commonalities 0.5.0-alpha.1 (r2.1) +* Identity and Consent Management v0.3.0-alpha.1 (r2.1) + +It contains the following changes compared to the last public release [r1.3](#r13) + +### Changed +All changes are to align with Commonalities 0.5.0-alpha.1 +* Error names and structures updated +* `security` component updated +* `x-camara-commonalities` version updated +* Template text for identifying devices updated +* Test guidelines updated to incorporate changed errrors. +* New API Readiness checklist used and updated + # r1.3 This release contains the definition and documentation of From 62541102ed28513bb2899f40fc965ee68e74e524 Mon Sep 17 00:00:00 2001 From: Kevin Smith Date: Fri, 3 Jan 2025 14:46:42 +0000 Subject: [PATCH 19/22] Remove 406 and 5xx errors, fixes #62 --- .../simple-edge-discovery.yaml | 162 ------------------ 1 file changed, 162 deletions(-) diff --git a/code/API_definitions/simple-edge-discovery.yaml b/code/API_definitions/simple-edge-discovery.yaml index e07ff88..7fab64d 100644 --- a/code/API_definitions/simple-edge-discovery.yaml +++ b/code/API_definitions/simple-edge-discovery.yaml @@ -361,22 +361,10 @@ paths: $ref: "#/components/responses/Generic403" "404": $ref: "#/components/responses/Generic404" - "406": - $ref: "#/components/responses/Generic406" "422": $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" tags: - Discovery @@ -640,31 +628,6 @@ components: status: 404 code: IDENTIFIER_NOT_FOUND message: Device identifier not found. - Generic406: - description: Not Acceptable - headers: - x-correlator: - $ref: "#/components/headers/x-correlator" - content: - application/json: - schema: - 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: @@ -752,128 +715,3 @@ components: status: 429 code: TOO_MANY_REQUESTS message: Either out of resource quota or reaching rate limiting. - Generic500: - description: Internal Server Error - headers: - 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 - 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 - 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 - 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: - - 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: - 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. From 5ed53186b1cb8118ed218828518d29975d8ebe11 Mon Sep 17 00:00:00 2001 From: Kevin Smith Date: Fri, 3 Jan 2025 14:52:02 +0000 Subject: [PATCH 20/22] Added security description, fixes #63 --- code/API_definitions/simple-edge-discovery.yaml | 1 + 1 file changed, 1 insertion(+) diff --git a/code/API_definitions/simple-edge-discovery.yaml b/code/API_definitions/simple-edge-discovery.yaml index 7fab64d..34926de 100644 --- a/code/API_definitions/simple-edge-discovery.yaml +++ b/code/API_definitions/simple-edge-discovery.yaml @@ -379,6 +379,7 @@ paths: components: securitySchemes: openId: + description: Common security scheme for all CAMARA APIs type: openIdConnect openIdConnectUrl: https://example.com/.well-known/openid-configuration From d153d673a820c382fca0de9a7060f0513412646f Mon Sep 17 00:00:00 2001 From: Kevin Smith Date: Fri, 3 Jan 2025 14:55:16 +0000 Subject: [PATCH 21/22] trailing whitespace --- code/API_definitions/simple-edge-discovery.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/code/API_definitions/simple-edge-discovery.yaml b/code/API_definitions/simple-edge-discovery.yaml index 34926de..980819b 100644 --- a/code/API_definitions/simple-edge-discovery.yaml +++ b/code/API_definitions/simple-edge-discovery.yaml @@ -379,7 +379,7 @@ paths: components: securitySchemes: openId: - description: Common security scheme for all CAMARA APIs + description: Common security scheme for all CAMARA APIs type: openIdConnect openIdConnectUrl: https://example.com/.well-known/openid-configuration From d6f1d75f61e7898d0353a7cf30e7ea76df47b5e2 Mon Sep 17 00:00:00 2001 From: Kevin Smith Date: Mon, 13 Jan 2025 16:25:18 +0000 Subject: [PATCH 22/22] fix x-camara-commonalities fixes #64 --- code/API_definitions/simple-edge-discovery.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/code/API_definitions/simple-edge-discovery.yaml b/code/API_definitions/simple-edge-discovery.yaml index 980819b..2c8b66c 100644 --- a/code/API_definitions/simple-edge-discovery.yaml +++ b/code/API_definitions/simple-edge-discovery.yaml @@ -3,7 +3,7 @@ openapi: 3.0.3 info: title: Simple Edge Discovery version: wip - x-camara-commonalities: 0.5.0 + x-camara-commonalities: 0.5 description: | # Find the closest Edge Cloud Zone ---