diff --git a/CHANGELOG.md b/CHANGELOG.md index 1ceec42..d37fc26 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,11 +2,88 @@ ## Table of Contents +- [r1.1](#r11) - [v0.2.0](#v020) - [v0.1.0](#v010) **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 it has been released. For example, changes may be reverted before a release is published. For the best results, use the latest published release.** +The below sections record the changes for each API version in each release as follows: + +* for each first alpha or release-candidate API version, all changes since the release of the previous public API version +* for subsequent alpha or release-candidate API versions, the delta with respect to the previous pre-release +* for a public API version, the consolidated changes since the release of the previous public API version + +# r1.1 + +## Release Notes + +This release contains the definition and documentation of +* location-verification v1.0.0-rc.1 +* location-retrieval v0.3.0-rc.1 +* geofencing-subscriptions v0.3.0-rc.1 + +The API definition(s) are based on +* Commonalities v0.4.0-rc.1 +* Identity and Consent Management v0.2.0-rc.1 + +**Full Changelog** with the list of PRs and contributors: https://github.com/camaraproject/DeviceLocation/compare/v0.2.0...r1.1 + +## location-verification v1.0.0-rc.1 + +### Added + +* Added x-correlator to requests and headers +* Enhancements in documentation +* Testing plan + +### Changed + +* Make `device` optional in requests, with related documentation +* Make '+' mandatory for phoneNumber +* Adjust `maxAge` behaviour and minimum, and adjust documentation +* Alignment of errors with Commonalities + +### Fixed + +* Update the PARTIAL case description: `match_rate` is set in the response + +## location-retrieval v0.3.0-rc.1 + +### Added + +* Added x-correlator to requests and headers +* Enhancements in documentation +* Testing plan + +### Changed + +* Make `device` optional in requests, with related documentation +* Make '+' mandatory for phoneNumber +* Adjust `maxAge` behaviour and minimum, and adjust documentation +* Alignment of errors with Commonalities + +### Fixed + +* Clarify that `lastLocationTime` is mandatory in responses + +## geofencing-subscriptions v0.3.0-rc.1 + +### Added + +* Adopt Commonalities guidelines for subscriptions (based on CloudEvents) +* Add `subscriptionMaxEvents` for maximum number of notifications +* Add `SUBSCRIPTION_DELETED` as termination-reason +* Added x-correlator to requests and headers +* Enhancements in documentation +* Testing plan + +### Changed + +* Change base path to `geofencing-subscriptions` and adapt security scopes +* Make '+' mandatory for phoneNumber +* Alignment of errors with Commonalities + # v0.2.0 **This is the second alpha version of the DeviceLocation API family.** diff --git a/README.md b/README.md index 9caefbc..abf5118 100644 --- a/README.md +++ b/README.md @@ -11,41 +11,33 @@ Repository to describe, develop, document and test the DeviceLocation API family ## Scope * Service APIs for “Device Location” (see APIBacklog.md) * It provides the customer with the ability to: - * verify the location of a device. - * retrieve the location of a device. - * subscribe and receive notifications about a device entering or leaving certain location (geofencing). + * verify the location of a device (location-verification). + * retrieve the location of a device (location-retrieval). + * subscribe and receive notifications about a device entering or leaving certain location (geofencing-subscriptions). * NOTE: The scope of this API family should be limited (at least at a first stage) to 4G and 5G. * Describe, develop, document and test the APIs (with 1-2 Telcos) * Started: July 2022 * Location: virtually -## Meetings -* Meetings are held virtually -* Schedule: bi-weekly (odd weeks), Tuesday, 9 AM CET/CEST -* Meeting link: [Registration / Join](https://zoom-lfx.platform.linuxfoundation.org/meeting/91878854906?password=7e620a89-fcb5-4d2d-927a-17e3a0d1d28e) -* Slack channel: [camara-project.slack.com](https://join.slack.com/t/camara-project/shared_invite/zt-26gy3e64n-o7Riy3MoXmzdaDEL3wlngg) #sp-device-location +## Release Information + +* The latest public release is available here: https://github.com/camaraproject/DeviceLocation/releases/latest +* For changes see [CHANGELOG.md](https://github.com/camaraproject/DeviceLocation/blob/main/CHANGELOG.md) -## Status and released versions * 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 available release**. -* **The latest available release for the DeviceLocation API family is 0.2.0.** There are bug fixes to be expected and incompatible changes in upcoming releases. It is suitable for implementors, but it is not recommended to use the API with customers in productive environments. - -* Release 0.2.0 of the API family is available within the [release-v0.2.0 branch](https://github.com/camaraproject/DeviceLocation/tree/release-v0.2.0). The API family now includes 3 APIs, in different state of progress: - - **location-verification v0.2.0**, which is the second alpha release of this API. - - OpenAPI [YAML spec file](https://github.com/camaraproject/DeviceLocation/blob/release-v0.2.0/code/API_definitions/location-verification.yaml) - - [View it on ReDoc](https://redocly.github.io/redoc/?url=https://raw.githubusercontent.com/camaraproject/DeviceLocation/release-v0.2.0/code/API_definitions/location-verification.yaml&nocors) - - [View it on Swagger Editor](https://editor.swagger.io/?url=https://raw.githubusercontent.com/camaraproject/DeviceLocation/release-v0.2.0/code/API_definitions/location-verification.yaml) - - **location-retrieval v0.1.0**, which is the first alpha release. - - OpenAPI [YAML spec file](https://github.com/camaraproject/DeviceLocation/blob/release-v0.2.0/code/API_definitions/location-retrieval.yaml) - - [View it on ReDoc](https://redocly.github.io/redoc/?url=https://raw.githubusercontent.com/camaraproject/DeviceLocation/release-v0.2.0/code/API_definitions/location-retrieval.yaml&nocors) - - [View it on Swagger Editor](https://editor.swagger.io/?url=https://raw.githubusercontent.com/camaraproject/DeviceLocation/release-v0.2.0/code/API_definitions/location-retrieval.yaml) - - **geofencing v0.1.0**, which is the first alpha release. - - OpenAPI [YAML spec file](https://github.com/camaraproject/DeviceLocation/blob/release-v0.2.0/code/API_definitions/geofencing.yaml) - - [View it on ReDoc](https://redocly.github.io/redoc/?url=https://raw.githubusercontent.com/camaraproject/DeviceLocation/release-v0.2.0/code/API_definitions/geofencing.yaml&nocors) - - [View it on Swagger Editor](https://editor.swagger.io/?url=https://raw.githubusercontent.com/camaraproject/DeviceLocation/release-v0.2.0/code/API_definitions/geofencing.yaml) - -* The previous release version v0.1.0 of DeviceLocation API is available within the [release-0.1.0 branch](https://github.com/camaraproject/DeviceLocation/tree/release-v0.1.0) - - This past release only included the first alpha version of the API now renamed to location-verification, but it was then named as "location v0.1.0" - -## Contributorship and mailing list -* To subscribe / unsubscribe to the mailing list of this Sub Project and thus be / resign as Contributor please visit . -* A message to all Contributors of this Sub Project can be sent using . + +* The latest pre-release is [r1.1](https://github.com/camaraproject/DeviceLocation/tree/r1.1) +The release r1.1 contains the following API definitions (with inline documentation): + - **location-verification v1.0.0-rc.1** [[YAML OAS]](https://github.com/camaraproject/DeviceLocation/blob/r1.1/code/API_definitions/location-verification.yaml) [[View it on ReDoc]](https://redocly.github.io/redoc/?url=https://raw.githubusercontent.com/camaraproject/DeviceLocation/r1.1/code/API_definitions/location-verification.yaml&nocors) [[View it on Swagger Editor]](https://editor.swagger.io/?url=https://raw.githubusercontent.com/camaraproject/DeviceLocation/r1.1/code/API_definitions/location-verification.yaml) + - **location-retrieval v0.3.0-rc.1** [[YAML OAS]](https://github.com/camaraproject/DeviceLocation/blob/r1.1/code/API_definitions/location-retrieval.yaml) [[View it on ReDoc]](https://redocly.github.io/redoc/?url=https://raw.githubusercontent.com/camaraproject/DeviceLocation/r1.1/code/API_definitions/location-retrieval.yaml&nocors) [[View it on Swagger Editor]](https://editor.swagger.io/?url=https://raw.githubusercontent.com/camaraproject/DeviceLocation/r1.1/code/API_definitions/location-retrieval.yaml) + - **geofencing-subscriptions v0.3.0-rc.1** [[YAML OAS]](https://github.com/camaraproject/DeviceLocation/blob/r1.1/code/API_definitions/geofencing.yaml) [[View it on ReDoc]](https://redocly.github.io/redoc/?url=https://raw.githubusercontent.com/camaraproject/DeviceLocation/r1.1/code/API_definitions/geofencing.yaml&nocors) [[View it on Swagger Editor]](https://editor.swagger.io/?url=https://raw.githubusercontent.com/camaraproject/DeviceLocation/r1.1/code/API_definitions/geofencing.yaml) + +## Contributing + +* Meetings are held virtually + - Schedule: bi-weekly (odd weeks), Tuesday, 9 AM CET/CEST + - Meeting link: [Registration / Join](https://zoom-lfx.platform.linuxfoundation.org/meeting/91878854906?password=7e620a89-fcb5-4d2d-927a-17e3a0d1d28e) +* Mailing list: + - To subscribe / unsubscribe to the mailing list of this Sub Project, please visit . + - A message to the community of this Sub Project can be sent using . +* Slack channel: [camara-project.slack.com](https://join.slack.com/t/camara-project/shared_invite/zt-26gy3e64n-o7Riy3MoXmzdaDEL3wlngg) #sp-device-location diff --git a/code/API_definitions/geofencing-subscriptions.yaml b/code/API_definitions/geofencing-subscriptions.yaml index 5134898..6e92bd9 100644 --- a/code/API_definitions/geofencing-subscriptions.yaml +++ b/code/API_definitions/geofencing-subscriptions.yaml @@ -62,7 +62,7 @@ info: # Authorization and authentication - [Camara Security and Interoperability Profile](https://github.com/camaraproject/IdentityAndConsentManagement/blob/main/documentation/CAMARA-Security-Interoperability.md) provides details on how a client requests an access token. + The "Camara Security and Interoperability Profile" provides details on how a client requests an access token. Please refer to Identify and Consent Management (https://github.com/camaraproject/IdentityAndConsentManagement/) for the released version of the Profile. Which specific authorization flows are to be used will be determined during onboarding process, happening between the API Client and the Telco Operator exposing the API, taking into account the declared purpose for accessing the API, while also being subject to the prevailing legal framework dictated by local legislation. @@ -72,7 +72,7 @@ info: (FAQs will be added in a later version of the documentation) - version: wip + version: 0.3.0-rc.1 license: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0.html @@ -82,7 +82,7 @@ externalDocs: url: https://github.com/camaraproject/DeviceLocation servers: - - url: "{apiRoot}/geofencing-subscriptions/vwip" + - url: "{apiRoot}/geofencing-subscriptions/v0.3rc1" variables: apiRoot: default: http://localhost:9091 diff --git a/code/API_definitions/location-retrieval.yaml b/code/API_definitions/location-retrieval.yaml index 5ed2a47..557f836 100644 --- a/code/API_definitions/location-retrieval.yaml +++ b/code/API_definitions/location-retrieval.yaml @@ -54,7 +54,7 @@ info: # Authorization and authentication - [Camara Security and Interoperability Profile](https://github.com/camaraproject/IdentityAndConsentManagement/blob/main/documentation/CAMARA-Security-Interoperability.md) provides details on how a client requests an access token. + The "Camara Security and Interoperability Profile" provides details on how a client requests an access token. Please refer to Identify and Consent Management (https://github.com/camaraproject/IdentityAndConsentManagement/) for the released version of the Profile. Which specific authorization flows are to be used will be determined during onboarding process, happening between the API Client and the Telco Operator exposing the API, taking into account the declared purpose for accessing the API, while also being subject to the prevailing legal framework dictated by local legislation. @@ -87,7 +87,7 @@ info: # Further info and support (FAQs will be added in a later version of the documentation) - version: wip + version: 0.3.0-rc.1 license: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0.html @@ -96,7 +96,7 @@ externalDocs: description: Project documentation at Camara url: https://github.com/camaraproject/DeviceLocation servers: - - url: '{apiRoot}/location-retrieval/vwip' + - url: '{apiRoot}/location-retrieval/v0.3rc1' variables: apiRoot: default: http://localhost:9091 diff --git a/code/API_definitions/location-verification.yaml b/code/API_definitions/location-verification.yaml index 3894d16..18eeb8a 100644 --- a/code/API_definitions/location-verification.yaml +++ b/code/API_definitions/location-verification.yaml @@ -47,7 +47,7 @@ info: # Authorization and authentication - [Camara Security and Interoperability Profile](https://github.com/camaraproject/IdentityAndConsentManagement/blob/main/documentation/CAMARA-Security-Interoperability.md) provides details on how a client requests an access token. + The "Camara Security and Interoperability Profile" provides details on how a client requests an access token. Please refer to Identify and Consent Management (https://github.com/camaraproject/IdentityAndConsentManagement/) for the released version of the Profile. Which specific authorization flows are to be used will be determined during onboarding process, happening between the API Client and the Telco Operator exposing the API, taking into account the declared purpose for accessing the API, while also being subject to the prevailing legal framework dictated by local legislation. @@ -80,7 +80,7 @@ info: # Further info and support (FAQs will be added in a later version of the documentation) - version: wip + version: 1.0.0-rc.1 license: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0.html @@ -89,7 +89,7 @@ externalDocs: description: Project documentation at CAMARA url: https://github.com/camaraproject/DeviceLocation servers: - - url: "{apiRoot}/location-verification/vwip" + - url: "{apiRoot}/location-verification/v1rc1" variables: apiRoot: default: http://localhost:9091 diff --git a/code/Test_definitions/Location-Retrieval.feature b/code/Test_definitions/Location-Retrieval.feature index 4c64d60..551ec6d 100644 --- a/code/Test_definitions/Location-Retrieval.feature +++ b/code/Test_definitions/Location-Retrieval.feature @@ -1,4 +1,4 @@ -Feature: CAMARA Device location retrieval API, v0.2.0 - Operation retrieveLocation +Feature: CAMARA Device location retrieval API, v0.3-rc.1 - Operation retrieveLocation # Input to be provided by the implementation to the tester # # Implementation indications: @@ -12,7 +12,7 @@ Feature: CAMARA Device location retrieval API, v0.2.0 - Operation retrieveLocat # References to OAS spec schemas refer to schemas specifies in location-retrieval.yaml, version 0.2.0 Background: Common retrieveLocation setup - Given the resource "/location-retrieval/v0/retrieve" | + Given the resource "/location-retrieval/v0.3rc1/retrieve" | 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" is set to a UUID value diff --git a/code/Test_definitions/location-verification.feature b/code/Test_definitions/location-verification.feature index 566c306..dee2622 100644 --- a/code/Test_definitions/location-verification.feature +++ b/code/Test_definitions/location-verification.feature @@ -1,4 +1,4 @@ -Feature: CAMARA Device location verification API, vWIP - Operation verifyLocation +Feature: CAMARA Device location verification API, v1.0-rc1 - Operation verifyLocation # Input to be provided by the implementation to the tester # # Implementation indications: diff --git a/documentation/API_documentation/geofencing-subscriptions-API-Readiness-Checklist.md b/documentation/API_documentation/geofencing-subscriptions-API-Readiness-Checklist.md index 60ddaef..3039486 100644 --- a/documentation/API_documentation/geofencing-subscriptions-API-Readiness-Checklist.md +++ b/documentation/API_documentation/geofencing-subscriptions-API-Readiness-Checklist.md @@ -1,27 +1,22 @@ # API Readiness Checklist -Checklist for geofencing-subscriptions api-version in v0.3 - -As we target an **initial** maturity level release, the column **Status** is filled accordingly: NA: Not Applicable, TBD: To Be Done +Checklist for geofencing-subscriptions 0.3.0-rc.1 in r1.1 | Nr | API release assets | alpha | release-candidate | public-release
initial | public-release
stable | Status | Comments | |----|----------------------------------------------|:-----:|:-----------------:|:-------------------------:|:-------------------------:|:------:|:--------------------------------------------------------------------------------------------------------------------------------------------------------:| -| 1 | API definition | M | M | M | M | Y | [link](/code/API_definitions/geofencing-subscriptions.yaml) | +| 1 | API definition | M | M | M | M | Y | /code/API_definitions/geofencing-subscriptions.yaml | | 2 | Design guidelines from Commonalities applied | O | M | M | M | Y | | | 3 | Guidelines from ICM applied | O | M | M | M | Y | | | 4 | API versioning convention applied | M | M | M | M | Y | | -| 5 | API documentation | M | M | M | M | Y | Embed documentation into API spec - [link](/code/API_definitions/geofencing-subscriptions.yaml) | +| 5 | API documentation | M | M | M | M | Y | inline in yaml | | 6 | User stories | O | O | O | M | NA | link | -| 7 | Basic API test cases & documentation | O | M | M | M | TBD | link | +| 7 | Basic API test cases & documentation | O | M | M | M | tbd | PR: /pull/181 | | 8 | Enhanced API test cases & documentation | O | O | O | M | NA | link | | 9 | Test result statement | O | O | O | M | NA | link | -| 10 | API release numbering convention applied | M | M | M | M | TBD | | -| 11 | Change log updated | M | M | M | M | TBD | link | +| 10 | API release numbering convention applied | M | M | M | M | Y | | +| 11 | Change log updated | M | M | M | M | Y | /CHANGELOG.md | | 12 | Previous public-release was certified | O | O | O | M | NA | | +Note: the checklists of a public API version and of its preceding release-candidate API version can be the same. - - -Note: It is normal that the checklists of the (final) release-candidate and its further public-release are the same, while additional release assets are required for the following stable public-release. - -The documentation for the content of the checklist is here: [API Readiness Checklist documentation](https://wiki.camaraproject.org/x/AgAVAQ#APIReleaseProcess-APIreadinesschecklist) +The documentation for the content of the checklist is here: [API Readiness Checklist](https://wiki.camaraproject.org/display/CAM/API+Release+Process#APIReleaseProcess-APIreadinesschecklist). diff --git a/documentation/API_documentation/location-retrieval-API-Readiness-Checklist.md b/documentation/API_documentation/location-retrieval-API-Readiness-Checklist.md index 83ae87e..e78c6c9 100644 --- a/documentation/API_documentation/location-retrieval-API-Readiness-Checklist.md +++ b/documentation/API_documentation/location-retrieval-API-Readiness-Checklist.md @@ -2,27 +2,21 @@ Checklist for location-retrieval 0.3.0-rc.1 in r1.1 - -As we target an **initial** maturity level release the column **Status** is filled accordingly: NA: Not Applicable, TBD: To Be Done - | Nr | API release assets | alpha | release-candidate | public-release
initial | public-release
stable | Status | Comments | |----|----------------------------------------------|:-----:|:-----------------:|:-------:|:------:|:----:|:----:| -| 1 | API definition | M | M | M | M | Y | [link](https://github.com/camaraproject/DeviceLocation/blob/main/code/API_definitions/location-retrieval.yaml) | +| 1 | API definition | M | M | M | M | Y | /code/API_definitions/location-retrieval.yaml | | 2 | Design guidelines from Commonalities applied | O | M | M | M | Y | | | 3 | Guidelines from ICM applied | O | M | M | M | Y | | | 4 | API versioning convention applied | M | M | M | M | Y | | -| 5 | API documentation | M | M | M | M | Y | Embed documentation into API spec - [link](https://github.com/camaraproject/DeviceLocation/blob/main/code/API_definitions/location-retrieval.yaml) | +| 5 | API documentation | M | M | M | M | Y | inline in yaml | | 6 | User stories | O | O | O | M | NA | link | -| 7 | Basic API test cases & documentation | O | M | M | M | TBD | link | +| 7 | Basic API test cases & documentation | O | M | M | M | Y | /code/Test_definitions/location-retrieval.feature | | 8 | Enhanced API test cases & documentation | O | O | O | M | NA | link | | 9 | Test result statement | O | O | O | M | NA | link | -| 10 | API release numbering convention applied | M | M | M | M | TBD | | -| 11 | Change log updated | M | M | M | M | TBD | link | +| 10 | API release numbering convention applied | M | M | M | M | Y | | +| 11 | Change log updated | M | M | M | M | Y | /CHANGELOG.md | | 12 | Previous public-release was certified | O | O | O | M | NA | | +Note: the checklists of a public API version and of its preceding release-candidate API version can be the same. - - -Note: It is normal that the checklists of the (final) release-candidate and its subsequent public-release are the same, while additional release assets are required for a subsequent stable public-release. - -The documentation for the content of the checklist is here: [API Readiness Checklist documentation](https://wiki.camaraproject.org/x/AgAVAQ#APIReleaseProcess-APIreadinesschecklist) +The documentation for the content of the checklist is here: [API Readiness Checklist](https://wiki.camaraproject.org/display/CAM/API+Release+Process#APIReleaseProcess-APIreadinesschecklist). \ No newline at end of file diff --git a/documentation/API_documentation/location-verification-API-Readiness-Checklist.md b/documentation/API_documentation/location-verification-API-Readiness-Checklist.md index 2738ea8..f5ec205 100644 --- a/documentation/API_documentation/location-verification-API-Readiness-Checklist.md +++ b/documentation/API_documentation/location-verification-API-Readiness-Checklist.md @@ -9,10 +9,14 @@ Checklist for location-verification v1.0.0-rc.1 in r1.1. | 3 | Guidelines from ICM applied | O | M | M | M |Y| | | 4 | API versioning convention applied | M | M | M | M |Y| | | 5 | API documentation | M | M | M | M |Y| inline in yaml | -| 6 | User stories | O | O | O | M |TBC| link TBC | +| 6 | User stories | O | O | O | M |tbd| PR: /pull/227 | | 7 | Basic API test cases & documentation | O | M | M | M |Y| /code/Test_definitions/location-verification.feature | -| 8 | Enhanced API test cases & documentation | O | O | O | M |Y | /code/Test_definitions/location-verification.feature | -| 9 | Test result statement | O | O | O | M |TBC| link TBC | -| 10 | API release numbering convention applied | M | M | M | M |TBC| | -| 11 | Change log updated | M | M | M | M |TBC| /CHANGELOG.md | +| 8 | Enhanced API test cases & documentation | O | O | O | M |Y| /code/Test_definitions/location-verification.feature | +| 9 | Test result statement | O | O | O | M |tbd| link | +| 10 | API release numbering convention applied | M | M | M | M |Y| | +| 11 | Change log updated | M | M | M | M |Y| /CHANGELOG.md | | 12 | Previous public release was certified | O | O | O | M |Y| | + +Note: the checklists of a public API version and of its preceding release-candidate API version can be the same. + +The documentation for the content of the checklist is here: [API Readiness Checklist](https://wiki.camaraproject.org/display/CAM/API+Release+Process#APIReleaseProcess-APIreadinesschecklist). \ No newline at end of file