r3.2

This public release contains the definition and documentation of

• location-verification v3.0.0
• location-retrieval v0.5.0
• geofencing-subscriptions v0.5.0

The API definition(s) are based on

• Commonalities r3.3
• Identity and Consent Management r3.3

location-verification v3.0.0

location-verification v3.0.0 is the public release for the next stable version of the API Location Verification.

There is breaking change compared to the previous release r2.2, due to the deprecation of UNKNOWN value for verificationResult in favor of the new error 422 LOCATION_VERIFICATION.UNABLE_TO_LOCATE.

• API definition with inline documentation:

  • View it on ReDoc
  • View it on Swagger Editor
  • OpenAPI YAML spec file

Added

• New error code 422 LOCATION_VERIFICATION.UNABLE_TO_LOCATE.
• New DeviceResponse object in responses limited to one identifier.
• Clarifications on non-documented error responses.

Changed

• Updated string pattern for x-correlatorheaders.
• Type of radius for CIRCLE Area changed from integer to number, and maximum removed.
• Clarified format for properties with format date-time.

Removed

• verificationResult: UNKNOWN for 200 responses.
• Error 422 IDENTIFIER_MISMATCH.
• Error 401 AUTHENTICATION_REQUIRED.

location-retrieval v0.5.0

location-retrieval v0.5.0 is the public release for the next initial version of the API Location Retrieval. It introduces breaking changes compared to the previous release r2.2, due to the deprecation of error 404 LOCATION_RETRIEVAL.DEVICE_NOT_FOUND in favor of the new error 422 LOCATION_RETRIEVAL.UNABLE_TO_LOCATE.

• API definition with inline documentation:

  • View it on ReDoc
  • View it on Swagger Editor
  • OpenAPI YAML spec file

Added

• New error 422 LOCATION_RETRIEVAL.UNABLE_TO_LOCATE.
• New DeviceResponse object in responses limited to one identifier.
• Clarifications on non-documented error responses.

Changed

• Updated string pattern for x-correlatorheaders.
• Clarified format for properties with format date-time.

Removed

• Error 404 LOCATION_RETRIEVAL.DEVICE_NOT_FOUND.
• Error 422 IDENTIFIER_MISMATCH.
• Error 401 AUTHENTICATION_REQUIRED.

geofencing-subscriptions v0.5.0

geofencing-subscriptions v0.5.0 is the public release for the next initial version of the API Geofencing Subscriptions. It introduces breaking changes compared to the previous release r2.2, coming from the alignment to the new guidelines in Commonalities for APIs with subscriptions.

• API definition with inline documentation:

  • View it on ReDoc
  • View it on Swagger Editor
  • OpenAPI YAML spec file

Added

• New subscription event types for subscription-started and subscription-updated.
• New DeviceResponse object in responses and events, limited to one identifier.
• Pattern to property sink and new error 400 INVALID_SINK.
• Clarifications on non-documented error responses.

Changed

• Subscription event type subscription-ends renamed to subscription-ended.
• Property id becomes required for SubscriptionAsync objects.
• operationId createSubscription renamed to createGeofencingSubscription.
• Updated string pattern for x-correlatorheaders.
• Type of radius for CIRCLE Area changed from integer to number, and maximum removed.
• Clarified format for properties with format date-time.

Fixed

• Subscription types array items must be limited to allowed SubscriptionEventType values

Removed

• Error 422 IDENTIFIER_MISMATCH.
• Error 401 AUTHENTICATION_REQUIRED.

r3.1

Release Notes

This pre-release contains the definition and documentation of

• location-verification v3.0.0-rc.1
• location-retrieval v0.5.0-rc.1
• geofencing-subscriptions v0.5.0-rc.1

The API definition(s) are based on

• Commonalities r3.2
• Identity and Consent Management r3.2

location-verification v3.0.0-rc.1

location-verification v3.0.0-rc.1 is the first release candidate for the next stable version of the API Location Verification. It introduces breaking changes compared to the previous release r2.2, due to the deprecation of UNKNOWN value for verificationResult in favor of the new error 422 LOCATION_VERIFICATION.UNABLE_TO_LOCATE.

• API definition with inline documentation:

  • View it on ReDoc
  • View it on Swagger Editor
  • OpenAPI YAML spec file

Added

• New error code 422 LOCATION_VERIFICATION.UNABLE_TO_LOCATE.
• New DeviceResponse object in responses limited to one identifier.
• Clarifications on non-documented error responses.

Changed

• Updated string pattern for x-correlatorheaders.

Removed

• verificationResult: UNKNOWN for 200 responses.
• Error 422 IDENTIFIER_MISMATCH.
• Error 401 AUTHENTICATION_REQUIRED.

location-retrieval v0.5.0-rc.1

location-retrieval v0.5.0-rc.1 is the first release candidate for the next initial version of the API Location Retrieval. It introduces breaking changes compared to the previous release r2.2, due to the deprecation of error 404 LOCATION_RETRIEVAL.DEVICE_NOT_FOUND in favor of the new error 422 LOCATION_RETRIEVAL.UNABLE_TO_LOCATE.

• API definition with inline documentation:

  • View it on ReDoc
  • View it on Swagger Editor
  • OpenAPI YAML spec file

Added

• New error 422 LOCATION_RETRIEVAL.UNABLE_TO_LOCATE.
• New DeviceResponse object in responses limited to one identifier.
• Clarifications on non-documented error responses.

Changed

• Updated string pattern for x-correlatorheaders

Removed

• Error 404 LOCATION_RETRIEVAL.DEVICE_NOT_FOUND.
• Error 422 IDENTIFIER_MISMATCH.
• Error 401 AUTHENTICATION_REQUIRED.

geofencing-subscriptions v0.5.0-rc.1

geofencing-subscriptions v0.5.0-rc.1 is the first release candidate for the next initial version of the API Geofencing Subscriptions. It introduces breaking changes compared to the previous release r2.2, coming from the alignment to the new guidelines in Commonalities for APIs with subscriptions.

• API definition with inline documentation:

  • View it on ReDoc
  • View it on Swagger Editor
  • OpenAPI YAML spec file

Added

• New subscription event types for subscription-started and subscription-updated
• New DeviceResponse object in responses and events, limited to one identifier.
• Pattern to property sink and new error 400 INVALID_SINK.
• Clarifications on non-documented error responses.

Changed

• Subscription event type subscription-ends renamed to subscription-ended
• Property id becomes required for SubscriptionAsync objects.
• operationId createSubscription renamed to createGeofencingSubscription
• Updated string pattern for x-correlatorheaders

Fixed

• Subscription types array items must be limited to allowed SubscriptionEventType values

Removed

• Error 422 IDENTIFIER_MISMATCH.
• Error 401 AUTHENTICATION_REQUIRED.

Full Changelog: r2.2...r3.1

r2.2

This public release contains the definition and documentation of

• location-verification v2.0.0
• location-retrieval v0.4.0
• geofencing-subscriptions v0.4.0

The API definition(s) are based on

• Commonalities r2.3
• Identity and Consent Management r2.3

Changelog since r1.2

• Full Changelog with the list of PRs and contributors: r1.2...r2.2

location-verification v2.0.0

There are breaking changes compared to v1.0.0: the API use has been simplified for API consumers using a three-legged access token to invoke the API.
In these cases the optional device parameter MUST NOT be provided, as the subject will be uniquely identified from the access token.
In this context also some error response codes have been renamed or replaced to comply with Commonalities 0.5.

Added

• Add MultiSIM section to info.description by @jlurien in #291
• Enhance description UNKNOWN vs UNABLE_TO_FULFILL_MAX_AGE by @jlurien in #314
• Section with guidelines about how to identify the device from access token and request body has been updated by @jlurien in #281

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
• Location verification align error tests by @jlurien in #306
• Some error status and codes have been updated by @jlurien in #281

Fixed

• Update error message for unsupported device identifiers by @maxl2287 in #261

• Add quote-marks for lastLocationTime - examples by @maxl2287 in #287

location-retrieval v0.4.0

There are breaking changes compared to v0.3.0: the API use has been simplified for API consumers using a three-legged access token to invoke the API.
In these cases the optional device parameter MUST NOT be provided, as the subject will be uniquely identified from the access token.
In this context also some error response codes have been renamed or replaced to comply with Commonalities 0.5.

Added

• Add management of maxSurface in request by @bigludo7 in #262
• Add MultiSIM section to info.description by @jlurien in #291
• Add LOCATION_RETRIEVAL.UNABLE_TO_FULFILL_MAX_SURFACE error by @bigludo7 in #303
• Section with guidelines about how to identify the device from access token and request body has been updated by @bigludo7 in #283

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
• Location Retrieval - Align Error Test by @bigludo7 in #310
• Location Retrieval - Remove unnecessary error 400 by @bigludo7 in #316
• Some error status and codes have been updated by @bigludo7 in #283

Fixed

• Update error message for unsupported device identifiers by @maxl2287 in #261

• Add quote-marks for lastLocationTime - examples by @maxl2287 in #287

geofencing-subscriptions v0.4.0

There are breaking changes compared to v0.3.0: the API use has been simplified for API consumers using a three-legged access token to invoke the API.
In these cases the optional device parameter MUST NOT be provided, as the subject will be uniquely identified from the access token.
In this context also some error response codes have been renamed or replaced to comply with Commonalities 0.5.

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
• Add "MISSING_IDENTIFIER" to the 422-error codes by @maxl2287 in #309
• Set Device Object To Optional - According to API Design Guidelines by @dfischer-tech in #298

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
• Alignment on commonalities r2.3 by @maxl2287 in #311
• Some error status and codes have been updated by @maxl2287 in #284

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

r2.1

This 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: 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.

• location-verification v2.0.0-rc.1 API definition with inline documentation:

  • View it on ReDoc

  • View it on Swagger Editor

  • OpenAPI YAML spec file

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.

• location-retrieval v0.4.0-rc.1 API definition with inline documentation:

  • View it on ReDoc

  • View it on Swagger Editor

  • OpenAPI YAML spec file

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.

• geofencing-subscriptions v0.4.0-rc.1 API definition with inline documentation:

  • View it on ReDoc

  • View it on Swagger Editor

  • OpenAPI YAML spec file

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

This public release contains the definition and documentation of

• location-verification v1.0.0
• location-retrieval v0.3.0
• geofencing-subscriptions v0.3.0

The API definition(s) are based on

• Commonalities v0.4.0
• Identity and Consent Management v0.2.0

Changelog since v0.2.0

• Full Changelog with the list of PRs and contributors: v0.2.0...r1.2

location-verification v1.0.0

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

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

Added

• Adopt Commonalities guidelines for subscriptions (based on CloudEvents)
• Add subscriptionMaxEvents for maximum number of notifications
• Add SUBSCRIPTION_DELETED and SUBSCRIPTION_UNPROCESSABLE as termination reasons
• Add terminationsDescription as optional event property
• 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

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

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

New Contributors

• @hdamker made their first contribution in #204
• @jgarciahospital made their first contribution in #226

Full Changelog: v0.2.0...r1.1

v0.2.0

This is the second alpha version of the Device Location API family

• API definition with inline documentation.

Please note:

• This release contains significant breaking changes compared to v0.1.0, and it is not backward compatible
  • Especially a lot of the parameter names changed in line with the agreed glossary within CAMARA Commonalities
• This is an alpha version, it should be considered as a draft.
• There are bug fixes to be expected and incompatible changes in upcoming versions.
• The release is suitable for implementers, but it is not recommended to use the API with customers in productive environments.

What's changed

• Second alpha version of location-verification API, v0.2.0, renamed from location, with main changes:

  • Input property ueId evolved to device, following CAMARA guidelines.
  • New input parameter area, considering initially circular areas, and deprecating previous latitude, longitude and accuracy properties.
  • New input parameter maxAge.
  • Response adds new values UNKNOWN and PARTIAL for verificationResult. It also adds properties matchRate and lastLocationTime.
  • Security schemas and scopes aligned with commonalities guidelines.
  • Error responses adapted to new commonalities guidelines.
  • Inline documentation within OpenAPI spec.

• First alpha version of the new API location-retrieval, v0.1.0:

  • Initial version already aligned with latest guidelines.
  • Returns 2 possible location areas: Circle and Polygon.

• First alpha version of the new API geofencing, v0.1.0:

  • Initial version already aligned with latest guidelines.
  • Follows CloudEvents format.

New Contributors

• @ukkaps made their first contribution in #9
• @VijayKesharwani made their first contribution in #22
• @rartych made their first contribution in #35
• @maheshc01 made their first contribution in #41
• @bigludo7 made their first contribution in #46
• @hbujakow made their first contribution in #53
• @maxl2287 made their first contribution in #98
• @eric-murray made their first contribution in #103

Full Changelog: v0.1.0...v0.2.0

v0.1.0

This is the first alpha version of the Device Location API.

• API definition
• API documentation

Please note:

• This is an alpha version, it should be considered as a draft.
• There are bug fixes to be expected and incompatible changes in upcoming versions.
• The release is suitable for implementors, but it is not recommended to use the API with customers in productive environments.

What's Changed

• Initial contribution of API spec location.yaml v0.1.0 by @akoshunyadi in #3
• Create Location_API.md by @jlurien in #11

New Contributors

• @akoshunyadi made their first contribution in #3
• @JoachimDahlgren made their first contribution in #1
• @shilpa-padgaonkar made their first contribution in #10
• @jlurien made their first contribution in #11

Full Changelog: https://github.com/camaraproject/DeviceLocation/commits/v0.1.0