diff --git a/CHANGELOG.md b/CHANGELOG.md index a6188a1..d50cd08 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,7 @@ NOTE: ## Table of contents +- [r2.2](#r22---Fall25-public-release) - [r2.1 - rc](#r21---rc) - [r1.3](#r13) - [r1.2 - rc](#r12---rc) @@ -23,6 +24,48 @@ The below sections record the changes for each API version in each release as fo NOTE: SimpleEdgeDiscovery is part of the EdgeCloud API Sub Project, 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. +# r2.2 - Fall25 public release + +This public release contains the definition and documentation of +* simple-edge-discovery v2.0.0 + +The API definition(s) are based on +* Commonalities v0.6.0 (r3.3) +* Identity and Consent Management v0.4.0 (r3.3) + +It contains the **following breaking changes** compared to the last public release [r1.3](#r13): + +* The API's single operation has been refactored from GET to POST +* The operation resource URI has changed from `/edge-cloud-zones?filter=closest` to `/retrieve-closest-edge-cloud-zone` +* One or more device identifiers must be passed either via a 3-legged access token or in the request body. + +- API definition with inline documentation: + - [View it on ReDoc](https://redocly.github.io/redoc/?url=https://raw.githubusercontent.com/camaraproject/SimpleEdgeDiscovery/r2.2/code/API_definitions/simple-edge-discovery.yaml&nocors) + - [View it on Swagger Editor](https://camaraproject.github.io/swagger-ui/?url=https://raw.githubusercontent.com/camaraproject/SimpleEdgeDiscovery/r2.2/code/API_definitions/simple-edge-discovery.yaml) + - [OpenAPI YAML spec file](https://github.com/camaraproject/SimpleEdgeDiscovery/blob/r2.2/code/API_definitions/simple-edge-discovery.yaml) + +### Added + +- [x] fix: added DeviceResponse object by @Kevsy in https://github.com/camaraproject/SimpleEdgeDiscovery/pull/102 +- [x] fix: added section on non-documented errors by @Kevsy in https://github.com/camaraproject/SimpleEdgeDiscovery/pull/92 + +### Changed + +- [x] refactor!: changed discovery operation method from GET to POST by @Kevsy in https://github.com/camaraproject/SimpleEdgeDiscovery/pull/78 +- [x] docs: updated examples and usage description following refactoring to POST by @Kevsy in https://github.com/camaraproject/SimpleEdgeDiscovery/pull/81 +- [x] refactor!: feature file updated to reflect change from GET to POST by @Kevsy in https://github.com/camaraproject/SimpleEdgeDiscovery/pull/118 +- [x] fix: updated 200 OK Response to a schema object by @Kevsy in https://github.com/camaraproject/SimpleEdgeDiscovery/pull/117 +- [x] fix: changed XCorrelator to an object and added resulting $refs by @Kevsy in https://github.com/camaraproject/SimpleEdgeDiscovery/pull/116 +- [x] fix: updated x-correlator pattern by @Kevsy in https://github.com/camaraproject/SimpleEdgeDiscovery/pull/93 +- [x] fix: updated x-camara-commonalities to 0.6 by @Kevsy in https://github.com/camaraproject/SimpleEdgeDiscovery/pull/101 +- [x] test: updated x-correlator in .feature to assert compliance with common schema by @Kevsy in https://github.com/camaraproject/SimpleEdgeDiscovery/pull/114 +- [x] docs: updated ref to Commonalities version in Device object description + +### Removed + +- [x] fix: removed 401 AUTHENTICATION_REQUIRED by @Kevsy in https://github.com/camaraproject/SimpleEdgeDiscovery/pull/90 +- [x] fix: removed 422 IDENTIFIER MISMATCH by @Kevsy in https://github.com/camaraproject/SimpleEdgeDiscovery/pull/89 + # r2.1 - rc This release candidate contains the definition and documentation of @@ -64,7 +107,6 @@ It contains the **following breaking changes** compared to the last public relea - [x] fix: removed 401 AUTHENTICATION_REQUIRED by @Kevsy in https://github.com/camaraproject/SimpleEdgeDiscovery/pull/90 - [x] fix: removed 422 IDENTIFIER MISMATCH by @Kevsy in https://github.com/camaraproject/SimpleEdgeDiscovery/pull/89 - # r1.3 This release contains the definition and documentation of diff --git a/README.md b/README.md index d039f45..f66b875 100644 --- a/README.md +++ b/README.md @@ -25,12 +25,12 @@ Incubating API Repository to evolve and maintain the definitions and documentati * Note: Please be aware that the project will have frequent updates to the main branch. There are no compatibility guarantees associated with code in any branch, including main, until a new release is created. For example, changes may be reverted before a release is created. **For best results, use the latest public release**. -* **The latest pre-release is [r2.1 - rc](https://github.com/camaraproject/SimpleEdgeDiscovery/releases/tag/r2.1), with the following API version:** +* **NEW: public release [r2.2](https://github.com/camaraproject/SimpleEdgeDiscovery/releases/tag/r2.2) is available, with the following API version:** - * **simple-edge-discovery v2.0.0-rc.1** - [[YAML]](https://github.com/camaraproject/SimpleEdgeDiscovery/blob/r2.1/code/API_definitions/simple-edge-discovery.yaml) - [[View it on ReDoc]](https://redocly.github.io/redoc/?url=https://raw.githubusercontent.com/camaraproject/SimpleEdgeDiscovery/r2.1/code/API_definitions/simple-edge-discovery.yaml&nocors) - [[View it on Swagger Editor]](https://camaraproject.github.io/swagger-ui/?url=https://raw.githubusercontent.com/camaraproject/SimpleEdgeDiscovery/r2.1/code/API_definitions/simple-edge-discovery.yaml) + * **simple-edge-discovery v2.0.0** + [[YAML]](https://github.com/camaraproject/SimpleEdgeDiscovery/blob/r2.2/code/API_definitions/simple-edge-discovery.yaml) + [[View it on ReDoc]](https://redocly.github.io/redoc/?url=https://raw.githubusercontent.com/camaraproject/SimpleEdgeDiscovery/r2.2/code/API_definitions/simple-edge-discovery.yaml&nocors) + [[View it on Swagger Editor]](https://camaraproject.github.io/swagger-ui/?url=https://raw.githubusercontent.com/camaraproject/SimpleEdgeDiscovery/r2.2/code/API_definitions/simple-edge-discovery.yaml) * Previous releases and pre-releases are available [here](https://github.com/camaraproject/SimpleEdgeDiscovery/releases) * For changes see [CHANGELOG.md](/CHANGELOG.md) diff --git a/code/API_definitions/simple-edge-discovery.yaml b/code/API_definitions/simple-edge-discovery.yaml index 913d4a2..300783b 100644 --- a/code/API_definitions/simple-edge-discovery.yaml +++ b/code/API_definitions/simple-edge-discovery.yaml @@ -2,7 +2,7 @@ openapi: 3.0.3 info: title: Simple Edge Discovery - version: wip + version: 2.0.0 x-camara-commonalities: 0.6 description: | # Find the closest Edge Cloud Zone @@ -20,7 +20,7 @@ info: physical (GPS) location of a user device is not a reliable way to determine the closest Edge Cloud Zone, due to the way operator networks are routed - so the operator will calculate the Edge Cloud Zone with the - _shortest network path_to the network-attached device identified in the API + _shortest network path_ to the network-attached device identified in the API request. Once you have the name of the closest Edge Cloud Zone to the user device, @@ -57,7 +57,7 @@ info: ## Passing device identifier(s) in the request At least one of the following device identifiers must be provided, unless - using a 3-legged access toekn (see next section): + using a 3-legged access token (see next section): - Phone number (i.e. MSISDN) - Network Access Identifier assigned by the mobile network operator for the device - IPv6 address @@ -189,7 +189,7 @@ externalDocs: url: https://github.com/camaraproject/EdgeCloud servers: - - url: "{apiRoot}/simple-edge-discovery/vwip" + - url: "{apiRoot}/simple-edge-discovery/v2" variables: apiRoot: default: https://localhost:9091 diff --git a/code/Test_definitions/simple-edge-discovery.feature b/code/Test_definitions/simple-edge-discovery.feature index b552447..352eceb 100644 --- a/code/Test_definitions/simple-edge-discovery.feature +++ b/code/Test_definitions/simple-edge-discovery.feature @@ -1,8 +1,8 @@ -Feature: CAMARA Simple Edge Discovery API, vwip - Operation readClosestEdgeCloudZone +Feature: CAMARA Simple Edge Discovery API, v2.0.0 - Operation readClosestEdgeCloudZone Background: Given an environment at "apiRoot" - And the resource "/simple-edge-discovery/vwip/retrieve-closest-edge-cloud-zone" | + And the resource "/simple-edge-discovery/v2/retrieve-closest-edge-cloud-zone" | And the header "Content-Type" is set to "application/json" And the header "Authorization" is set to a valid access token And the header "x-correlator" complies with the schema at "#/components/schemas/XCorrelator" @@ -32,12 +32,13 @@ Feature: CAMARA Simple Edge Discovery API, vwip - Operation readClosestEdgeCloud @simple_edge_discovery_error_scenario_01_404_device_cannot_be_identified Scenario: Error because the device cannot be identified - Given the request "readClosestEdgeCloudZone" is sent - When the provided identifier(s) cannot be matched to a device - Then the response status code is 422 + Given that the device cannot be identified from the access token + And the request body property "$.device" is compliant with the request body schema but does not identify a valid device + When the request "readClosestEdgeCloudZone" is sent + Then the response status code is 404 And the response header "x-correlator" has same value as the request header "x-correlator" And the response header "Content-Type" is "application/json" - And the response property "$.status" is 400 + And the response property "$.status" is 404 And the response property "$.code" is "IDENTIFIER_NOT_FOUND" And the response property "$.message" contains a user friendly text @@ -48,7 +49,7 @@ Feature: CAMARA Simple Edge Discovery API, vwip - Operation readClosestEdgeCloud Then the response status code is 422 And the response header "x-correlator" has same value as the request header "x-correlator" And the response header "Content-Type" is "application/json" - And the response property "$.status" is 400 + And the response property "$.status" is 422 And the response property "$.code" is "UNSUPPORTED_IDENTIFIER" And the response property "$.message" contains a user friendly text @@ -59,7 +60,7 @@ Feature: CAMARA Simple Edge Discovery API, vwip - Operation readClosestEdgeCloud Then the response status code is 422 And the response header "x-correlator" has same value as the request header "x-correlator" And the response header "Content-Type" is "application/json" - And the response property "$.status" is 400 + And the response property "$.status" is 422 And the response property "$.code" is "MISSING_IDENTIFIER" And the response property "$.message" contains a user friendly text @@ -70,7 +71,7 @@ Feature: CAMARA Simple Edge Discovery API, vwip - Operation readClosestEdgeCloud Then the response status code is 403 And the response header "x-correlator" has same value as the request header "x-correlator" And the response header "Content-Type" is "application/json" - And the response property "$.status" is 400 + And the response property "$.status" is 403 And the response property "$.code" is "INVALID_TOKEN_CONTEXT" And the response property "$.message" contains a user friendly text @@ -81,7 +82,7 @@ Feature: CAMARA Simple Edge Discovery API, vwip - Operation readClosestEdgeCloud Then the response status code is 422 And the response header "x-correlator" has same value as the request header "x-correlator" And the response header "Content-Type" is "application/json" - And the response property "$.status" is 400 + And the response property "$.status" is 422 And the response property "$.code" is "SERVICE_NOT_APPLICABLE" And the response property "$.message" contains a user friendly text 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 fca6e65..424fd38 100644 --- a/documentation/API_documentation/simple-edge-discovery_API_Readiness_Checklist.md +++ b/documentation/API_documentation/simple-edge-discovery_API_Readiness_Checklist.md @@ -1,18 +1,18 @@ # API Readiness Checklist -Checklist for simple-edge-discovery v2.0.0-rc.1 +Checklist for simple-edge-discovery v2.0.0 | Nr | API release assets | alpha | release-candidate | initial
public | stable
public | Status | Comments | |----|----------------------------------------------|:-----:|:-----------------:|:-------:|:------:|:----:|:----:| | 1 | API definition | M | M | M | M | Y | [link](/code/API_definitions/simple-edge-discovery.yaml) | -| 2 | Design guidelines from Commonalities applied | O | M | M | M | Y | [r3.2](https://github.com/camaraproject/Commonalities/releases/tag/r3.2) | -| 3 | Guidelines from ICM applied | O | M | M | M | Y | [r3.2](https://github.com/camaraproject/IdentityAndConsentManagement/releases/tag/r3.2) | +| 2 | Design guidelines from Commonalities applied | O | M | M | M | Y | [r3.3](https://github.com/camaraproject/Commonalities/releases/tag/r3.3) | +| 3 | Guidelines from ICM applied | O | M | M | M | Y | [r3.3](https://github.com/camaraproject/IdentityAndConsentManagement/releases/tag/r3.3) | | 4 | API versioning convention applied | M | M | M | M | Y | | | 5 | API documentation | M | M | M | M | Y | in yaml | | 6 | User stories | O | O | O | M | Y | [link](/documentation/API_documentation/SimpleEdgeDiscovery_User_Story.md) | | 7 | Basic API test cases & documentation | O | M | M | M | Y | [link](/code/Test_definitions) | | 8 | Enhanced API test cases & documentation | O | O | O | M | Y | [link](/code/Test_definitions) | -| 9 | Test result statement | O | O | O | M | N | N | +| 9 | Test result statement | O | O | O | M | Y | see [issue #128](https://github.com/camaraproject/SimpleEdgeDiscovery/issues/128) | | 10 | API release numbering convention applied | M | M | M | M | Y | Y | | 11 | Change log updated | M | M | M | M | Y | [link](/CHANGELOG.md) | | 12 | Previous public release was certified | O | O | O | M | Y | see (1) |