Merge pull request #41 from camaraproject/Kevsy-patch-7

SimpleEdgeDiscovery - PR for M4 - *PLEASE APPROVE as CODEOWNER and MERGE*
camaraproject · Sep 10, 2024 · 136a826 · 136a826
2 parents cb6af63 + a3137cf
commit 136a826
Show file tree

Hide file tree

Showing 5 changed files with 96 additions and 45 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -4,7 +4,8 @@ NOTE:
 
 ## Table of contents
 
-- **[r1.2 - rc](#r12---rc)**
+- [r1.3](#r13)
+- [r1.2 - rc](#r12---rc)
 - [r1.1 - rc](#r11---rc)
 - [r0.9.3 - rc](#r093---rc)
 - [r0.8.1](#r081)
@@ -22,6 +23,48 @@ 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.
 
+# r1.3
+
+This release contains the definition and documentation of
+* simple-edge-discovery v1.0.0, a stable public release.
+
+The API definition(s) are based on
+* Commonalities v0.4.0
+* Identity and Consent Management v0.2.0
+
+It contains the following changes compared to last public release [r0.9.3 - rc](#r093---rc):
+
+### Added
+  - Gherkin `.feature` file in Test_definitions
+  - Implementation of ICM consent guidelines
+  - Addition of `x-camara-commonalities` object to YAML
+  - Documentation: added warning about use of `networkAccessIdentifier`, added User Story
+
+### Changed
+  - info.version to 1.0.0
+  - version in servers.url to v1
+  - Changed `mecplatforms` to  `EdgeCloudZones` in alignment with EdgeCloud API family 
+  - Compliance with DeviceIdentifier schema
+  - The device identifier may now be available from a 3-legged access token 
+  - Change of `X-Correlator` to `x-correlator`
+  - `Operation` tag now follows agreed syntax
+  - Error model alignment, including device identifier-related errors
+  - Documentation: updated the API Readiness Checklist
+  - Documentation: clarified distinction between device/server usage of the SimpleEdgeDiscovery API
+  - Documentation: replaced term 'MNO' with 'network operator'
+  - Documentation: updated section on authentication and authorisation
+
+### Removed
+  - UUID format constraint from x-correlator 
+  - 405 Method Not Allowed error response
+  - Removed example for `networkAccessIdentifier`
+
+### Fixed
+  - Trailiing whitespace issues in YAML
+
+
+ Changelog from r1.3 to r1.2 only: https://github.com/camaraproject/SimpleEdgeDiscovery/compare/r1.2...r1.3
+
 # r1.2 - rc
 
 This release contains the definition and documentation of
@@ -41,7 +84,7 @@ It contains the following corrections compared to [r1.1 - rc](#r11---rc).
   - documentation: replaced term 'MNO' with 'network operator'
   - documentation: updated section on authentication and authorisation
 
-Full Changelog: https://github.com/camaraproject/SimpleEdgeDiscovery/compare/r1.1...r1.2  
+Full Changelog: https://github.com/camaraproject/SimpleEdgeDiscovery/compare/r1.1...r1.2
 
 
 # r1.1 - rc

diff --git a/README.md b/README.md
@@ -11,16 +11,18 @@ Repository to describe, develop, document, and test the SimpleEdgeDiscovery API
 
 ## Scope
 * Service APIs for “SimpleEdgeDiscovery” (see APIBacklog.md)  
-* It provides the customer with the ability to:  
+* It provides the API Consumer with the ability to:  
   * Discover the closest edge cloud zone to a given device..
   * NOTE: The scope of this API family should be limited (at least at the first stage) to 4G and 5G.  
 * Describe, develop, document, and test the APIs
 * Started: June 2022 (as part of https://github.com/camaraproject/EdgeCloud/)
 
 ## Release Information
 <!-- Use/uncomment one or multiple the following options -->
+The latest public release is available here: https://github.com/camaraproject/SimpleEdgeDiscovery/releases/latest
+
 Pre-releases of this sub project are available in https://github.com/camaraproject/SimpleEdgeDiscovery/releases
-<!-- The latest public release is available here: https://github.com/camaraproject/§repo_name§/releases/latest -->
+
 For changes see [CHANGELOG.md](https://github.com/camaraproject/SimpleEdgeDiscovery/blob/main/CHANGELOG.md)
 
 ## Contributing

diff --git a/code/API_definitions/simple-edge-discovery.yaml b/code/API_definitions/simple-edge-discovery.yaml
@@ -1,8 +1,8 @@
 ---
 openapi: 3.0.3
 info:
- title: Simple Edge Discovery API
- version: 0.11.0-rc.2
+ title: Simple Edge Discovery
+ version: 1.0.0
  x-camara-commonalities: 0.4.0
  description: |
   # Find the closest Edge Cloud Zone
@@ -50,7 +50,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 3-legged
-  access token where implemeented by the operator.
+  access token where implemented by the operator.
 
   ## Passing a device identifier in the request header
 
@@ -68,8 +68,8 @@ 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 request fails with a `404 Not Found` error
-  then retry the request but this time include a device identifier.
+  in the request header. If that returns a 422 `UNIDENTIFIABLE_DEVICE`
+  error then retry the request but this time include a device identifier.
 
   NOTE1: the network operator might support only a subset of these options.
   The API invoker can provide multiple identifiers to be compatible across
@@ -114,27 +114,48 @@ info:
 
   ## Identifying a device from the access token
 
-  This specification defines the `device` object field 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 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.
 
   ### Handling of device information:
 
-  #### Optional device object for 3-legged tokens:
+  #### Optional device identifying headers for 3-legged tokens:
 
-  - 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 the device object 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.
+  - 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.
 
   #### Validation mechanism:
 
-  - The server will extract the device identification from the access token, if available.
-  - If the API request additionally includes a `device` object 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.
+  - 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` object is not included in the request and the device information cannot be derived from the 3-legged access token, the server will return a 422 `UNIDENTIFIABLE_DEVICE` error.
+  - 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, the `device` object 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.
+  - 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.
 
   # Responses
 
@@ -233,7 +254,7 @@ externalDocs:
  url: https://github.com/camaraproject/EdgeCloud
 
 servers:
- - url: "{apiRoot}/simple-edge-discovery/v0.11rc2"
+ - url: "{apiRoot}/simple-edge-discovery/v1"
    variables:
     apiRoot:
      default: https://localhost:9091
@@ -320,7 +341,6 @@ paths:
         any valid value. Recommendation is to use UUID for values.
       schema:
        type: string
-       format: uuid
 
    responses:
     "200":
@@ -613,6 +633,12 @@ components:
         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
+       value:
+        status: 422
+        code: UNIDENTIFIABLE_DEVICE
+        message: The device cannot be identified.
    headers:
     x-correlator:
      $ref: "#/components/headers/x-correlator"

diff --git a/code/Test_definitions/simple-edge-discovery.feature b/code/Test_definitions/simple-edge-discovery.feature
@@ -1,24 +1,3 @@
-#/*- ---license-start
-#* CAMARA Project
-#* ---
-#* Copyright (C) 2022 - 2023 Contributors | Deutsche Telekom AG to CAMARA a Series of LF Projects, LLC
-#* The contributor of this file confirms his sign-off for the
-#* Developer Certificate of Origin (http://developercertificate.org).
-#* ---
-#* Licensed under the Apache License, Version 2.0 (the "License");
-#* you may not use this file except in compliance with the License.
-#* You may obtain a copy of the License at
-#*
-#*      http://www.apache.org/licenses/LICENSE-2.0
-#*
-#* Unless required by applicable law or agreed to in writing, software
-#* distributed under the License is distributed on an "AS IS" BASIS,
-#* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-#* See the License for the specific language governing permissions and
-#* limitations under the License.
-#* ---license-end
-#*/
-
 Feature: CAMARA Simple Edge Discovery API - Operation readClosestEdgeCloudZone
 
   Background:
@@ -52,7 +31,7 @@ Feature: CAMARA Simple Edge Discovery API - Operation readClosestEdgeCloudZone
   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 404 DEVICE_NOT_FOUND
+    Then Response code is 422 UNIDENTIFIABLE_DEVICE
 
   @simple_edge_discovery_5_error_device_identifiers_mismatch
   Scenario: Error because provided device indentifiers are inconsistent
@@ -72,7 +51,7 @@ Feature: CAMARA Simple Edge Discovery API - Operation readClosestEdgeCloudZone
     When The identified device is not connected to an edge-supporting network
     Then Response code is 422 DEVICE_NOT_APPLICABLE
 
-  @simple_edge_discovery_6_error_operator_cannot_resolve
+  @simple_edge_discovery_8_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

diff --git 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 v0.11.0-rc.1 in r1.1
+Checklist for simple-edge-discovery v1.0 in r1.3
 
 | Nr | API release assets  | alpha | release-candidate |  initial<br>public | stable<br> public | Status | Comments |
 |----|----------------------------------------------|:-----:|:-----------------:|:-------:|:------:|:----:|:----:|
@@ -11,9 +11,10 @@ Checklist for simple-edge-discovery v0.11.0-rc.1 in r1.1
 |  5 | API documentation                            |   M   |         M         |    M    |    M   |  Y   | [link](/code/API_definitions/simple-edge-discovery.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   |  M   | [link](/code/Test_definitions) |
-|  9 | Test result statement                        |   O   |         O         |    O    |    M   |  N   |  |
+|  8 | Enhanced API test cases & documentation      |   O   |         O         |    O    |    M   |  Y  | [link](/code/Test_definitions) |
+|  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)     |
 
+(*) 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.