Merge pull request #290 from maxl2287/prepare-release-r2.1

Pre-Release r2.1

CHANGELOG.md

@@ -2,7 +2,8 @@
 
 ## Table of Contents
 
-- **[r1.2](#r12)**
+- **[r2.1](#r21)**
+- [r1.2](#r12)
 - [r1.1](#r11)
 - [v0.2.0](#v020)
 - [v0.1.0](#v010)
@@ -11,9 +12,101 @@
 
 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
+* for an alpha release, the delta with respect to the previous release
+* for the first release-candidate, all changes since the last public release
+* for subsequent release-candidate(s), only the delta to the previous release-candidate
+* for a public release, the consolidated changes since the previous public release
+
+# r2.1
+
+## Release Notes
+
+This **public release** contains the definition and documentation of
+* location-verification v2.0.0-rc.1
+* location-retrieval v0.4.0-rc.1
+* geofencing-subscriptions v0.4.0-rc.1
+
+The API definition(s) are based on
+* Commonalities r2.2
+* Identity and Consent Management r2.2
+
+**Changelog since r1.2**
+
+
+* Full Changelog with the list of PRs and contributors: https://github.com/camaraproject/DeviceLocation/compare/r1.2...r2.1
+
+## location-verification v2.0.0-rc.1
+
+**Please be aware that this release contains breaking changes compared to the previous version.**
+
+### Breaking Changes
+* Some error status and codes have been updated by @jlurien in #281
+* Section with guidelines about how to identify the device from access token and request body has been updated by @jlurien in #281
+
+### Added
+
+* Add MultiSIM section to info.description by @jlurien in #291
+
+### Changed
+
+* Decrease radius minimum to "1" for circle-area by @maxl2287 in #285
+* Error schemas updated with enums by @jlurien in #281
+* Add pattern for x-correlator by @bigludo7 in #290
+* Update 429 error message by @bigludo7 in #290
+
+### Fixed
+* Update errormessage for unsupported device identifiers by @maxl2287 in #261
+* Add quote-marks for `lastLocationTime` - examples by @maxl2287 in #287
+
+## location-retrieval v0.4.0-rc.1
+**Please be aware that this release contains breaking changes compared to the previous version.**
+
+### Breaking Changes
+
+* Some error status and codes have been updated by @bigludo7 in #283
+* Section with guidelines about how to identify the device from access token and request body has been updated by @bigludo7 in #283
+
+### Added
+
+* Add management of `maxSurface` in request by @bigludo7 in #262
+* Add MultiSIM section to info.description by @jlurien in #291
+
+### Changed
+
+* Error schemas updated with enums by @bigludo7 in #283
+* Test definitions aligned with API specification update by @bigludo7 in #283
+* Add pattern for x-correlator by @bigludo7 in #290
+* Update 429 error message by @bigludo7 in #290
+
+### Fixed
+
+* Update errormessage for unsupported device identifiers by @maxl2287 in #261
+* Add quote-marks for `lastLocationTime` - examples by @maxl2287 in #287 
+
+## geofencing-subscriptions v0.4.0-rc.1
+**Please be aware that this release contains breaking changes compared to the previous version.**
+
+### Breaking Changes
+
+* Some error status and codes have been updated by @maxl2287 in #284
+
+### Added
+
+* Add test-definitions for HTTP-422 error-cases for geofencing-API by @maxl2287 in #289
+* Add MultiSIM section to info.description by @jlurien in #291
+
+### Changed
+
+* Decrease radius minimum to "1" for circle-area by @maxl2287 in #285
+* Error schemas updated with enums by @maxl2287 in #284
+* Add a note that initial events will be counted when `subscriptionMaxEvents` is combined with initialEvent=true by @maxl2287 in #284
+* Add pattern for x-correlator by @bigludo7 in #290
+* Update 429 error message by @bigludo7 in #290
+
+### Fixed
+* remove `allOf` in `sinkCredential` by @maxl2287 in #265
+* Correct the example for subscriptions regarding `initialEvent` and error `MULTIEVENT_SUBSCRIPTION_NOT_SUPPORTED` by @dfischer-tech in #267
+* Add quote-marks for `subscriptionExpireTime` - examples by @maxl2287 in #287
 
 # r1.2
 

README.md

@@ -27,11 +27,10 @@ Repository to describe, develop, document and test the DeviceLocation API family
 
 * 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 release is [r1.2](https://github.com/camaraproject/DeviceLocation/tree/r1.2) with the following API definitions (with inline documentation):
-  - **location-verification v1.0.0** [[YAML OAS]](https://github.com/camaraproject/DeviceLocation/blob/r1.2/code/API_definitions/location-verification.yaml) [[View it on ReDoc]](https://redocly.github.io/redoc/?url=https://raw.githubusercontent.com/camaraproject/DeviceLocation/r1.2/code/API_definitions/location-verification.yaml&nocors) [[View it on Swagger Editor]](https://editor.swagger.io/?url=https://raw.githubusercontent.com/camaraproject/DeviceLocation/r1.2/code/API_definitions/location-verification.yaml)
-  - **location-retrieval v0.3.0** [[YAML OAS]](https://github.com/camaraproject/DeviceLocation/blob/r1.2/code/API_definitions/location-retrieval.yaml) [[View it on ReDoc]](https://redocly.github.io/redoc/?url=https://raw.githubusercontent.com/camaraproject/DeviceLocation/r1.2/code/API_definitions/location-retrieval.yaml&nocors) [[View it on Swagger Editor]](https://editor.swagger.io/?url=https://raw.githubusercontent.com/camaraproject/DeviceLocation/r1.2/code/API_definitions/location-retrieval.yaml)
-  - **geofencing-subscriptions v0.3.0** [[YAML OAS]](https://github.com/camaraproject/DeviceLocation/blob/r1.2/code/API_definitions/geofencing-subscriptions.yaml) [[View it on ReDoc]](https://redocly.github.io/redoc/?url=https://raw.githubusercontent.com/camaraproject/DeviceLocation/r1.2/code/API_definitions/geofencing-subscriptions.yaml&nocors) [[View it on Swagger Editor]](https://editor.swagger.io/?url=https://raw.githubusercontent.com/camaraproject/DeviceLocation/r1.2/code/API_definitions/geofencing-subscriptions.yaml)
-
+* The latest pre-release is [r2.1](https://github.com/camaraproject/DeviceLocation/tree/r2.1) with the following API definitions (with inline documentation):
+  - **location-verification v2.0.0-rc.1** [[YAML OAS]](https://github.com/camaraproject/DeviceLocation/blob/r2.1/code/API_definitions/location-verification.yaml) [[View it on ReDoc]](https://redocly.github.io/redoc/?url=https://raw.githubusercontent.com/camaraproject/DeviceLocation/r2.1/code/API_definitions/location-verification.yaml&nocors) [[View it on Swagger Editor]](https://editor.swagger.io/?url=https://raw.githubusercontent.com/camaraproject/DeviceLocation/r2.1/code/API_definitions/location-verification.yaml)
+  - **location-retrieval v0.4.0-rc.1** [[YAML OAS]](https://github.com/camaraproject/DeviceLocation/blob/r2.1/code/API_definitions/location-retrieval.yaml) [[View it on ReDoc]](https://redocly.github.io/redoc/?url=https://raw.githubusercontent.com/camaraproject/DeviceLocation/r2.1/code/API_definitions/location-retrieval.yaml&nocors) [[View it on Swagger Editor]](https://editor.swagger.io/?url=https://raw.githubusercontent.com/camaraproject/DeviceLocation/r2.1/code/API_definitions/location-retrieval.yaml)
+  - **geofencing-subscriptions v0.4.0-rc.1** [[YAML OAS]](https://github.com/camaraproject/DeviceLocation/blob/r2.1/code/API_definitions/geofencing-subscriptions.yaml) [[View it on ReDoc]](https://redocly.github.io/redoc/?url=https://raw.githubusercontent.com/camaraproject/DeviceLocation/r2.1/code/API_definitions/geofencing-subscriptions.yaml&nocors) [[View it on Swagger Editor]](https://editor.swagger.io/?url=https://raw.githubusercontent.com/camaraproject/DeviceLocation/r2.1/code/API_definitions/geofencing-subscriptions.yaml)
 ## Contributing
 
 * Meetings are held virtually

code/API_definitions/geofencing-subscriptions.yaml

@@ -66,11 +66,11 @@ info:
 
     # Authorization and authentication
 
-    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.
+    The "Camara Security and Interoperability Profile" provides details of how an API consumer requests an access token. Please refer to Identity 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 API Provider, taking into account the declared purpose for accessing the API, while also being subject to the prevailing legal framework dictated by local legislation.
+    The specific authorization flows to be used will be agreed upon during the onboarding process, happening between the API consumer and the API provider, taking into account the declared purpose for accessing the API, whilst also being subject to the prevailing legal framework dictated by local legislation.
 
-    It is important to remark that in cases where personal user data is processed by the API, and users can exercise their rights through mechanisms such as opt-in and/or opt-out, the use of 3-legged access tokens becomes mandatory. This measure ensures that the API remains in strict compliance with user privacy preferences and regulatory obligations, upholding the principles of transparency and user-centric data control.
+    In cases where personal data is processed by the API and users can exercise their rights through mechanisms such as opt-in and/or opt-out, the use of three-legged access tokens is mandatory. This ensures that the API remains in compliance with privacy regulations, upholding the principles of transparency and user-centric privacy-by-design.
 
     # Multi-SIM scenario handling
 
@@ -90,17 +90,17 @@ info:
 
     (FAQs will be added in a later version of the documentation)
 
-  version: wip
+  version: 0.4.0-rc.1
   license:
     name: Apache 2.0
     url: https://www.apache.org/licenses/LICENSE-2.0.html
-  x-camara-commonalities: 0.5.0
+  x-camara-commonalities: 0.5
 externalDocs:
   description: Project documentation at Camara
   url: https://github.com/camaraproject/DeviceLocation
 
 servers:
-  - url: "{apiRoot}/geofencing-subscriptions/vwip"
+  - url: "{apiRoot}/geofencing-subscriptions/v0.4rc1"
     variables:
       apiRoot:
         default: http://localhost:9091
@@ -323,11 +323,13 @@ components:
       description: Correlation id for the different services.
       schema:
         type: string
+        pattern: ^[a-zA-Z0-9-]{0,55}$
   headers:
     x-correlator:
       description: Correlation id for the different services.
       schema:
         type: string
+        pattern: ^[a-zA-Z0-9-]{0,55}$
   schemas:
     ErrorInfo:
       description: The error info object for possible error cases.
@@ -1414,17 +1416,17 @@ components:
                       - TOO_MANY_REQUESTS
           examples:
             GENERIC_429_QUOTA_EXCEEDED:
-              description: Request is rejected due to exceeding a business quota limit.
+              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.
+                message: Out of resource quota.
             GENERIC_429_TOO_MANY_REQUESTS:
-              description: API Server request limit is overpassed.
+              description: Access to the API has been temporarily blocked due to rate or spike arrest limits being reached
               value:
                 status: 429
                 code: TOO_MANY_REQUESTS
-                message: Either out of resource quota or reaching rate limiting.
+                message: Rate limit reached.
   examples:
     REQUEST_CIRCLE_AREA_ENTERED:
       description: A sample geofence for entering for a circle area.

code/API_definitions/location-retrieval.yaml

@@ -64,11 +64,11 @@ info:
 
     # Authorization and authentication
 
-    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.
+    The "Camara Security and Interoperability Profile" provides details of how an API consumer requests an access token. Please refer to Identity 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 API Provider, taking into account the declared purpose for accessing the API, while also being subject to the prevailing legal framework dictated by local legislation.
+    The specific authorization flows to be used will be agreed upon during the onboarding process, happening between the API consumer and the API provider, taking into account the declared purpose for accessing the API, whilst also being subject to the prevailing legal framework dictated by local legislation.
 
-    It is important to remark that in cases where personal user data is processed by the API, and users can exercise their rights through mechanisms such as opt-in and/or opt-out, the use of 3-legged access tokens becomes mandatory. This measure ensures that the API remains in strict compliance with user privacy preferences and regulatory obligations, upholding the principles of transparency and user-centric data control.
+    In cases where personal data is processed by the API and users can exercise their rights through mechanisms such as opt-in and/or opt-out, the use of three-legged access tokens is mandatory. This ensures that the API remains in compliance with privacy regulations, upholding the principles of transparency and user-centric privacy-by-design.
 
     # Identifying the device from the access token
 
@@ -101,16 +101,16 @@ info:
     # Further info and support
 
     (FAQs will be added in a later version of the documentation)
-  version: wip
+  version: 0.4.0-rc.1
   license:
     name: Apache 2.0
     url: https://www.apache.org/licenses/LICENSE-2.0.html
-  x-camara-commonalities: 0.5.0
+  x-camara-commonalities: 0.5
 externalDocs:
   description: Project documentation at Camara
   url: https://github.com/camaraproject/DeviceLocation
 servers:
-  - url: '{apiRoot}/location-retrieval/vwip'
+  - url: '{apiRoot}/location-retrieval/v0.4rc1'
     variables:
       apiRoot:
         default: http://localhost:9091
@@ -209,11 +209,13 @@ components:
       description: Correlation id for the different services
       schema:
         type: string
+        pattern: ^[a-zA-Z0-9-]{0,55}$
   headers:
     x-correlator:
       description: Correlation id for the different services
       schema:
         type: string
+        pattern: ^[a-zA-Z0-9-]{0,55}$
   schemas:
     RetrievalLocationRequest:
       description: Request to retrieve the location of a device. Device is not required when using a 3-legged access token, following the rules in the description.
@@ -639,13 +641,13 @@ components:
               value:
                 status: 429
                 code: QUOTA_EXCEEDED
-                message: Either out of resource quota or reaching rate limiting.
+                message: Out of resource quota.
             GENERIC_429_TOO_MANY_REQUESTS:
-              description: API Server request limit is overpassed
+              description: Access to the API has been temporarily blocked due to rate or spike arrest limits being reached
               value:
                 status: 429
                 code: TOO_MANY_REQUESTS
-                message: Either out of resource quota or reaching rate limiting.
+                message: Rate limit reached.
   examples:
     RETRIEVAL_CIRCLE:
       summary: circle-based device location retrieval

code/API_definitions/location-verification.yaml

@@ -50,11 +50,11 @@ info:
 
     # Authorization and authentication
 
-    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.
+    The "Camara Security and Interoperability Profile" provides details of how an API consumer requests an access token. Please refer to Identity 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 API Provider, taking into account the declared purpose for accessing the API, while also being subject to the prevailing legal framework dictated by local legislation.
+    The specific authorization flows to be used will be agreed upon during the onboarding process, happening between the API consumer and the API provider, taking into account the declared purpose for accessing the API, whilst also being subject to the prevailing legal framework dictated by local legislation.
 
-    It is important to remark that in cases where personal user data is processed by the API, and users can exercise their rights through mechanisms such as opt-in and/or opt-out, the use of 3-legged access tokens becomes mandatory. This measure ensures that the API remains in strict compliance with user privacy preferences and regulatory obligations, upholding the principles of transparency and user-centric data control.
+    In cases where personal data is processed by the API and users can exercise their rights through mechanisms such as opt-in and/or opt-out, the use of three-legged access tokens is mandatory. This ensures that the API remains in compliance with privacy regulations, upholding the principles of transparency and user-centric privacy-by-design.
 
     # Identifying the device from the access token
 
@@ -87,16 +87,16 @@ info:
     # Further info and support
 
     (FAQs will be added in a later version of the documentation)
-  version: wip
+  version: 2.0.0-rc.1
   license:
     name: Apache 2.0
     url: https://www.apache.org/licenses/LICENSE-2.0.html
-  x-camara-commonalities: 0.5.0
+  x-camara-commonalities: 0.5
 externalDocs:
   description: Project documentation at CAMARA
   url: https://github.com/camaraproject/DeviceLocation
 servers:
-  - url: "{apiRoot}/location-verification/vwip"
+  - url: "{apiRoot}/location-verification/v2rc1"
     variables:
       apiRoot:
         default: http://localhost:9091
@@ -223,11 +223,13 @@ components:
       description: Correlation id for the different services
       schema:
         type: string
+        pattern: ^[a-zA-Z0-9-]{0,55}$
   headers:
     x-correlator:
       description: Correlation id for the different services
       schema:
         type: string
+        pattern: ^[a-zA-Z0-9-]{0,55}$
   schemas:
     Area:
       description: Base schema for all areas
@@ -683,10 +685,10 @@ components:
               value:
                 status: 429
                 code: QUOTA_EXCEEDED
-                message: Either out of resource quota or reaching rate limiting.
+                message: Out of resource quota.
             GENERIC_429_TOO_MANY_REQUESTS:
-              description: API Server request limit is overpassed
+              description: Access to the API has been temporarily blocked due to rate or spike arrest limits being reached
               value:
                 status: 429
                 code: TOO_MANY_REQUESTS
-                message: Either out of resource quota or reaching rate limiting.
+                message: Rate limit reached.