From 429ca8e2ffa6ae096d317f6afb672de94537b3c0 Mon Sep 17 00:00:00 2001 From: Jose Luis Urien Date: Fri, 26 Jul 2024 10:24:59 +0200 Subject: [PATCH] Revert "Prepare release 1.1 for location-verification + README + CHANGELOG" --- CHANGELOG.md | 76 ------------------- README.md | 54 +++++++------ .../location-verification.yaml | 64 ++++++---------- .../location-verification.feature | 26 ++----- 4 files changed, 62 insertions(+), 158 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 15e64932..1ceec425 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,87 +2,11 @@ ## 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 -* 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 014d82ac..9caefbc7 100644 --- a/README.md +++ b/README.md @@ -11,33 +11,41 @@ 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 (location-verification). - * retrieve the location of a device (location-retrieval). - * subscribe and receive notifications about a device entering or leaving certain location (geofencing-subscriptions). + * 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). * 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 -## 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) +## 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 +## 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 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** [[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** [[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** [[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 \ No newline at end of file +* **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 . diff --git a/code/API_definitions/location-verification.yaml b/code/API_definitions/location-verification.yaml index c3b38079..6d796eb4 100644 --- a/code/API_definitions/location-verification.yaml +++ b/code/API_definitions/location-verification.yaml @@ -6,7 +6,7 @@ info: # Introduction - Customers are able to verify whether the location of certain user device is within the area specified. Currently the only area supported as input is a circle determined by a set of coordinates (latitude and longitude) and some expected accuracy (radius). + Customers are able to verify whether the location of certain user device is within the area specified. Currently the only area supported as input is a circle determined by the a set of coordinates (latitude and longitude) and some expected accuracy (radius). The verification result depends on the network's ability and accuracy to locate the device at the requested area. @@ -15,9 +15,9 @@ info: * If the network's estimation of the device's location partially overlaps with the requested area, or it fully contains the requested area (because it is larger), the result is 'PARTIAL'. In this case, a `match_rate` is included in the response, indicating an estimation of the likelihood of the match in percent. * Lastly, the network may not be able to locate the device. In this case, the verification result is `UNKNOWN`. - The client may optionally include a `maxAge` indication. If the location information known to the server is older than the specified `maxAge`, an error 422 with code LOCATION_VERIFICATION.UNABLE_TO_FULFILL_MAX_AGE is sent back. + The client may optionally include a `maxAge` indication. If the location information known to the server is older than the specified `maxAge`, the verification result will be `UNKNOWN` and the `lastLocationTime` attribute may indicate the last available time for the device location. - `lastLocationTime` will be always included in the success response unless there is no historical location information available for the device. In this case, `UNKNOWN` will be returned without `lastLocationTime`. + `lastLocationTime` will be always included in the response unless there is no historical location information available for the device. In this case, `UNKNOWN` will be returned without `lastLocationTime`. Location Verification could be useful in scenarios such as: @@ -33,7 +33,7 @@ info: * **Area**: It specifies the geographical surface where a device may be physically located. * **Max Age**: Maximum age of the location information which is accepted for the location verification (in seconds). - * Absence of maxAge means "any age" is acceptable for the client. In other words, this is like maxAge=infinite. In this case the system will still return lastLocationTime, if available. + * Absence of maxAge means "any age" is acceptable for the client. In other words, this is like maxAge=infinite. In this case the system may still return lastLocationTime, if available. * maxAge=0 means a fresh calculation is requested by the client. If the system is not able to provide the fresh location, an error 422 with code LOCATION_VERIFICATION.UNABLE_TO_FULFILL_MAX_AGE is sent back. @@ -80,23 +80,25 @@ info: # Further info and support (FAQs will be added in a later version of the documentation) - version: 1.0.0-rc.1 + termsOfService: http://swagger.io/terms/ + contact: + email: project-email@sample.com license: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0.html - x-camara-commonalities: 0.4.0 + version: 0.3.0-wip externalDocs: description: Product documentation at CAMARA url: https://github.com/camaraproject/ servers: - - url: "{apiRoot}/location-verification/v1rc1" + - url: "{apiRoot}/location-verification/v0" variables: apiRoot: default: http://localhost:9091 description: API root tags: - name: Location verification - description: Verification of the location of a device + description: Verification the location of a device paths: /verify: post: @@ -130,7 +132,7 @@ paths: maxAge: 120 INPUT_IP_ADDRESS_V4_CIRCLE: summary: IPv4 address, circle, without maxAge - description: Verify if device identified by an IPv4 address is within a circle, not indicating a maxAge + description: Verify if device identified by an IPv4 address is within a circle value: device: ipv4Address: @@ -152,7 +154,6 @@ paths: latitude: 50.735851 longitude: 7.10066 radius: 50000 - maxAge: 120 responses: "200": description: Location verification result @@ -176,9 +177,15 @@ paths: value: verificationResult: "FALSE" lastLocationTime: 2023-09-07T10:40:52Z - VERIFICATION_UNKNOWN: - summary: Unknown - description: The network cannot locate the device + VERIFICATION_UNKNOWN_WITH_LAST_LOCATION_TIME: + summary: Unknown with last location time + description: The network cannot locate the device after the requested maxAge + value: + verificationResult: "UNKNOWN" + lastLocationTime: 2023-09-07T10:40:52Z + VERIFICATION_UNKNOWN_WITHOUT_LAST_LOCATION_TIME: + summary: Unknown without last location time + description: The network cannot locate the device and there is no history available value: verificationResult: "UNKNOWN" VERIFICATION_PARTIAL: @@ -198,8 +205,6 @@ paths: $ref: "#/components/responses/Generic404" "422": $ref: "#/components/responses/VerifyLocationUnprocessableEntity422" - "429": - $ref: "#/components/responses/Generic429" "500": $ref: "#/components/responses/Generic500" "503": @@ -257,7 +262,7 @@ components: $ref: "#/components/schemas/Point" radius: type: integer - description: Expected accuracy for the verification in meters, from center + description: Expected accuracy for the verification in meters, from location (radius) minimum: 2000 maximum: 200000 required: @@ -302,7 +307,7 @@ components: example: 7.10066 VerifyLocationRequest: - description: Request to verify the location of a device. Device is not required when using a 3-legged access token, following the rules in the description. + description: Request to verify the location of a device type: object properties: device: @@ -406,7 +411,7 @@ components: example: 2001:db8:85a3:8d3:1319:8a2e:370:7344 MaxAge: - description: The maximum age (in seconds) for the location known by the implementation, which is accepted for the verification. Absence of maxAge means "any age" and maxAge=0 means a fresh calculation. + description: The maximum age (in seconds) of the available location, which is accepted for the verification. Absence of maxAge means "any age" and maxAge=0 means a fresh calculation. type: integer example: 120 @@ -608,29 +613,6 @@ components: code: UNIDENTIFIABLE_DEVICE message: "A device must be provided" - Generic429: - description: Too Many Requests - headers: - x-correlator: - $ref: "#/components/headers/x-correlator" - 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. - Generic500: description: Internal server error headers: diff --git a/code/Test_definitions/location-verification.feature b/code/Test_definitions/location-verification.feature index a5423584..91154678 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, v1.0.0-rc.1 - Operation verifyLocation +Feature: CAMARA Device location verification API, vwip - Operation verifyLocation # Input to be provided by the implementation to the tester # # Implementation indications: @@ -12,8 +12,7 @@ Feature: CAMARA Device location verification API, v1.0.0-rc.1 - Operation verify # References to OAS spec schemas refer to schemas specifies in location-verification.yaml, version 0.2.0 Background: Common verifyLocation setup - Given the resource "/location-verification/v1rc1/verify" | - + Given the resource "/location-verification/v0/verify" | 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 @@ -23,7 +22,7 @@ Feature: CAMARA Device location verification API, v1.0.0-rc.1 - Operation verify @location_verification_01_generic_success_scenario Scenario: Common validations for any sucess scenario # Valid testing device and default request body compliant with the schema - Given a valid testing device supported by the service, identified by the token or provided in the request body + Given the request body property "$.device" is set to a valid testing device supported by the service And the request body is set to a valid request body When the HTTP "POST" request is sent Then the response status code is 200 @@ -39,7 +38,7 @@ Feature: CAMARA Device location verification API, v1.0.0-rc.1 - Operation verify @location_verification_02_known_location_for_device_no_maxAge Scenario: Known location of a device without specifying maxAge - Given a valid testing device supported by the service, identified by the token or provided in the request body + Given the request body property "$.device" is set to a valid testing device located by the network And the request body property "$.area" is set to the known location of the device And the request body property "$.maxAge" is not included When the HTTP "POST" request is sent @@ -54,7 +53,7 @@ Feature: CAMARA Device location verification API, v1.0.0-rc.1 - Operation verify @location_verification_03_known_location_for_device_with_maxAge Scenario Outline: Known location of a device specifying maxAge - Given a valid testing device supported by the service identified, by the token or provided in the request body + Given the request body property "$.device" is set to a valid testing device located by the network And the request body property "$.area" is set to the known location of the device And the request body property "$.maxAge" is included When the HTTP "POST" request is sent @@ -69,7 +68,7 @@ Feature: CAMARA Device location verification API, v1.0.0-rc.1 - Operation verify @location_verification_04_false_location_for_device Scenario: False location of a device - Given a valid testing device supported by the service identified, by the token or provided in the request body + Given the request body property "$.device" is set to a valid testing device located by the network And the request body property "$.area" is set to a wrong location of the device When the HTTP "POST" request is sent Then the response status code is 200 @@ -83,7 +82,7 @@ Feature: CAMARA Device location verification API, v1.0.0-rc.1 - Operation verify @location_verification_05_unknown_location_for_device Scenario: Unknown location of a device specifying maxAge - Given a valid testing device supported by the service, identified by the token or provided in the request body, which is not connected to the network for some time + Given the request body property "$.device" is set to a valid testing device which is not connected to the network for some time And the request body property "$.maxAge" is set to a value shorter than that time When the HTTP "POST" request is sent Then the response status code is 200 @@ -172,16 +171,6 @@ Feature: CAMARA Device location verification API, v1.0.0-rc.1 - Operation verify And the response property "$.code" is "DEVICE_NOT_APPLICABLE" And the response property "$.message" contains a user friendly text - @location_verification_17_unidentifiable_device - Scenario: Device not inlcuded and cannot be deducted from the access token - Given the header "Authorization" is set to a valid access which does not identifiy a single device - And the request body property "$.device" is not included - When the HTTP "POST" request is sent - Then the response status code is 422 - And the response property "$.status" is 422 - And the response property "$.code" is "UNIDENTIFIABLE_DEVICE" - And the response property "$.message" contains a user friendly text - # Generic 400 errors @location_verification_400.1_no_request_body @@ -233,6 +222,7 @@ Feature: CAMARA Device location verification API, v1.0.0-rc.1 - Operation verify Examples: | input_property | + | $.device | | $.area | | $.area.areaType | | $.area.center |