Release of API location-retrieval version 1.0.0-rc.1

code/API_definitions/location-retrieval.yaml

@@ -64,13 +64,11 @@ info:
     # Further info and support
 
     (FAQs will be added in a later version of the documentation)
-  termsOfService: http://swagger.io/terms/
-  contact:
-    email: [email protected]
   license:
     name: Apache 2.0
     url: https://www.apache.org/licenses/LICENSE-2.0.html
-  version: 0.2.0-wip
+  version: 0.3.0-rc.1
+  x-camara-commonalities: 0.4.0
 externalDocs:
   description: Product documentation at Camara
   url: https://github.com/camaraproject/
@@ -118,7 +116,7 @@ paths:
                 LOCATION_POLYGON:
                   $ref: "#/components/examples/RETRIEVAL_POLYGON"
         '400':
-          $ref: '#/components/responses/RetrieveLocationBadRequest400'
+          $ref: '#/components/responses/Generic400'
         '401':
           $ref: '#/components/responses/Generic401'
         '403':
@@ -357,55 +355,83 @@ components:
         message:
           type: string
           description: Detailed error description
+
   responses:
-    RetrieveLocationBadRequest400:
-      description: |-
-        Problem with the client request. In addition to regular scenario of `INVALID_ARGUMENT`, another scenarios may exist:
-          - maxAge threshold cannot be satisfied
+    Generic400:
+      description: Bad Request
       headers:
         x-correlator:
-          $ref: '#/components/headers/x-correlator'
+          $ref: "#/components/headers/x-correlator"
       content:
         application/json:
           schema:
-            $ref: '#/components/schemas/ErrorInfo'
+            $ref: "#/components/schemas/ErrorInfo"
           examples:
-            InvalidArgument:
+            GENERIC_400_INVALID_ARGUMENT:
+              summary: Generic Invalid Argument
+              description: Invalid Argument. Generic Syntax Exception
               value:
                 status: 400
                 code: INVALID_ARGUMENT
-                message: "Invalid argument"
-            MaxAgeIssue:
+                message: Client specified an invalid argument, request body or query param.
+            GENERIC_400_OUT_OF_RANGE:
+              summary: Generic Out of Range
+              description: Out of Range. Specific Syntax Exception used when a given field has a pre-defined range or a invalid filter criteria combination is requested
               value:
                 status: 400
-                code: LOCATION_RETRIEVAL.MAXAGE_INVALID_ARGUMENT
-                message: "maxAge threshold cannot be satisfied"
+                code: OUT_OF_RANGE
+                message: Client specified an invalid range.
+
     Generic401:
-      description: Unauthenticated
+      description: Unauthorized
       headers:
         x-correlator:
-          $ref: '#/components/headers/x-correlator'
+          $ref: "#/components/headers/x-correlator"
       content:
         application/json:
           schema:
-            $ref: '#/components/schemas/ErrorInfo'
-          example:
-            status: 401
-            code: UNAUTHENTICATED
-            message: "Authorization failed: ..."
+            $ref: "#/components/schemas/ErrorInfo"
+          examples:
+            GENERIC_401_UNAUTHENTICATED:
+              summary: Generic Unauthenticated
+              description: Request cannot be authenticated
+              value:
+                status: 401
+                code: UNAUTHENTICATED
+                message: Request not authenticated due to missing, invalid, or expired credentials.
+            GENERIC_401_AUTHENTICATION_REQUIRED:
+              summary: Generic Authentication Required
+              description: New authentication is needed, authentication is no longer valid
+              value:
+                status: 401
+                code: AUTHENTICATION_REQUIRED
+                message: New authentication is required.
+
     Generic403:
-      description: Permission denied
+      description: Forbidden
       headers:
         x-correlator:
-          $ref: '#/components/headers/x-correlator'
+          $ref: "#/components/headers/x-correlator"
       content:
         application/json:
           schema:
-            $ref: '#/components/schemas/ErrorInfo'
-          example:
-            status: 403
-            code: PERMISSION_DENIED
-            message: "Operation not allowed: ..."
+            $ref: "#/components/schemas/ErrorInfo"
+          examples:
+            GENERIC_403_PERMISSION_DENIED:
+              summary: Generic Permission Denied
+              description: Permission denied. OAuth2 token access does not have the required scope or when the user fails operational security
+              value:
+                status: 403
+                code: PERMISSION_DENIED
+                message: Client does not have sufficient permissions to perform this action.
+            GENERIC_403_INVALID_TOKEN_CONTEXT:
+              summary: Invalid access token context
+              description: Reflects some inconsistency between information in some field of the API and the related OAuth2 Token
+              value:
+                status: 403
+                code: INVALID_TOKEN_CONTEXT
+                message: "{{field}} is not consistent with access token."
+
     RetrieveLocationNotFound404:
       description: Not found
       headers:
@@ -416,16 +442,21 @@ components:
           schema:
             $ref: '#/components/schemas/ErrorInfo'
           examples:
-            notFound:
-              value:
-                status: 404
-                code: NOT_FOUND
-                message: 'The specified resource is not found'
-            deviceNotFound:
+            LOCATION_RETRIEVAL_404_UNABLE_TO_LOCATE_DEVICE:
+              summary: The location server is not able to locate the device
+              description: The location server is not able to locate the device
               value:
                 status: 404
                 code: LOCATION_RETRIEVAL.DEVICE_NOT_FOUND
                 message: 'The location server is not able to locate the mobile'
+            GENERIC_404_DEVICE_NOT_FOUND:
+              summary: Some identifier cannot be matched to a device
+              description: One or more of the provided device identifiers do not match any device
+              value:
+                status: 404
+                code: DEVICE_NOT_FOUND
+                message: "No device found for a provided identifier"
+
     RetrieveLocationUnprocessableEntity422:
       description: Unprocessable Entity
       headers:
@@ -435,38 +466,88 @@ components:
         application/json:
           schema:
             $ref: '#/components/schemas/ErrorInfo'
-          example:
-            status: 422
-            code: LOCATION_RETRIEVAL.UNABLE_TO_FULFILL_MAX_AGE
-            message: "Unable to provide expected frehsness for location"
+          examples:
+            LOCATION_RETRIEVAL_422_UNABLE_TO_FULFILL_MAX_AGE:
+              summary: Unable to provide expected frehsness
+              description: Unable to provide expected frehsness for location retrieval request
+              value:
+                status: 422
+                code: LOCATION_RETRIEVAL.UNABLE_TO_FULFILL_MAX_AGE
+                message: "Unable to provide expected frehsness for location"
+            GENERIC_422_UNPROCESSABLE_ENTITY:
+              summary: Unprocessable entity
+              description: The request was well-formed but was unable to be processed due to semantic errors or not applicable values. This is the generic error code for 422 responses.
+              value:
+                status: 422
+                code: UNPROCESSABLE_ENTITY
+                message: "Value not acceptable: ..."
+            GENERIC_422_DEVICE_NOT_APPLICABLE:
+              summary: Service not applicable to the device
+              description: The provided device is not compatible with the requested operation, according to the service provider rules.
+              value:
+                status: 422
+                code: DEVICE_NOT_APPLICABLE
+                message: "The device is not applicable for the requested operation"
+            GENERIC_422_DEVICE_IDENTIFIERS_MISMATCH:
+              summary: Device identifiers mismatch
+              description: Several device identifiers are provided but do not match the same device
+              value:
+                status: 422
+                code: DEVICE_IDENTIFIERS_MISMATCH
+                message: "The provided device identifiers do not match the same device"
+            GENERIC_422_UNSUPPORTED_DEVICE_IDENTIFIERS:
+              summary: None of the provided device identifiers is supported by the implementation
+              description: Message may list the supported device identifiers
+              value:
+                status: 422
+                code: UNSUPPORTED_DEVICE_IDENTIFIERS
+                message: "Supported device supported are: ..."
+            GENERIC_422_UNIDENTIFIABLE_DEVICE:
+              summary: No identifier provided
+              description: No device identifier provided for the device to be located
+              value:
+                status: 422
+                code: UNIDENTIFIABLE_DEVICE
+                message: "A device must be provided"
     Generic500:
       description: Internal server error
       headers:
         x-correlator:
-          $ref: '#/components/headers/x-correlator'
+          $ref: "#/components/headers/x-correlator"
       content:
         application/json:
           schema:
-            $ref: '#/components/schemas/ErrorInfo'
-          example:
-            status: 500
-            code: INTERNAL
-            message: "Internal server error"
+            $ref: "#/components/schemas/ErrorInfo"
+          examples:
+            GENERIC_500_INTERNAL:
+              summary: Generic Internal
+              description: Problem in Server side. Regular Server Exception
+              value:
+                status: 500
+                code: INTERNAL
+                message: "Internal server error"
+
     Generic503:
-      description: Service unavailable
+      description: Service Unavailable
       headers:
         x-correlator:
-          $ref: '#/components/headers/x-correlator'
+          $ref: "#/components/headers/x-correlator"
       content:
         application/json:
           schema:
-            $ref: '#/components/schemas/ErrorInfo'
-          example:
-            status: 503
-            code: UNAVAILABLE
-            message: "Service unavailable"
+            $ref: "#/components/schemas/ErrorInfo"
+          examples:
+            GENERIC_503_UNAVAILABLE:
+              summary: Generic Unavailable
+              description: Service is not available. Temporary situation usually related to maintenance process in the server side
+              value:
+                status: 503
+                code: UNAVAILABLE
+                message: Service Unavailable.
+
   examples:
     RETRIEVAL_CIRCLE:
+      summary: circle-based device location retrieval
       value:
         lastLocationTime: 2023-10-17T13:18:23.682Z
         area:
@@ -476,6 +557,7 @@ components:
             longitude: 4.860374
           radius: 800
     RETRIEVAL_POLYGON:
+      summary: polygon-based device location retrieval
       value:
         lastLocationTime: 2023-10-17T13:18:23.682Z
         area:

location-retrieval CHANGELOG.md

@@ -0,0 +1,64 @@
+# Changelog location-retrieval from DeviceLocation API family
+
+## Table of Contents
+
+- [v0.2.0](#v020rc1)
+- [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.**
+
+# v0.2.0.rc1
+
+
+## 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 implementors, but it is not recommended to use the API with customers in productive environments
+
+## Added
+
+
+* Test Definition in Test_Definitions directory (PR229)
+*  Add x-correlator as header parameter (commonalities alignement) (PR172)
+
+## Changed
+
+* Make the '+' mandatory for the phone number (PR178)
+* Remove minimum 60 seconds to maxAge (PR188)
+  -  Absence of maxAge means "any age"
+  -  maxAge=0 means a fresh calculation.
+* Cosmetic change following megalinter integration by @bigludo7 
+* Update Authorization and authentication part accordingly to ICM (PR217)
+* Align the documentation part of the API with the fact that lastLocationTime is mandatory in all response. (PR199)
+* - Aligned error code list & description with Commonalities (PR221)
+
+### Fixed
+
+* n/a
+
+### Removed
+
+* n/a
+
+# v0.1.0
+
+**This is the fist alpha version of the location-retrieval API but it was part of second alpha version of the DeviceLocation API family.**
+
+- API [definition](https://github.com/camaraproject/DeviceLocation/blob/release-0.2.0-rc3/code/API_definitions/location-retrieval.yaml) **with inline documentation**.
+
+
+## Added
+
+
+* 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`.
+
+
+
+
+

location-retrieval README.md

@@ -0,0 +1,42 @@
+<a href="https://github.com/camaraproject/DeviceLocation/commits/" title="Last Commit"><img src="https://img.shields.io/github/last-commit/camaraproject/DeviceLocation?style=plastic"></a>
+<a href="https://github.com/camaraproject/DeviceLocation/issues" title="Open Issues"><img src="https://img.shields.io/github/issues/camaraproject/DeviceLocation?style=plastic"></a>
+<a href="https://github.com/camaraproject/DeviceLocation/pulls" title="Open Pull Requests"><img src="https://img.shields.io/github/issues-pr/camaraproject/DeviceLocation?style=plastic"></a>
+<a href="https://github.com/camaraproject/DeviceLocation/graphs/contributors" title="Contributors"><img src="https://img.shields.io/github/contributors/camaraproject/DeviceLocation?style=plastic"></a>
+<a href="https://github.com/camaraproject/DeviceLocation" title="Repo Size"><img src="https://img.shields.io/github/repo-size/camaraproject/DeviceLocation?style=plastic"></a>
+<a href="https://github.com/camaraproject/DeviceLocation/blob/main/LICENSE" title="License"><img src="https://img.shields.io/badge/License-Apache%202.0-green.svg?style=plastic"></a>
+
+# Location Retrieval API
+Repository to describe, develop, document and test the Location retrieval API
+**Location retrieval API is part of the Device Location API family**
+
+## Scope
+* Service APIs for “location-retrieval” (see APIBacklog.md)  
+* It provides the customer with the ability to retrieve the location of a device.
+* NOTE: The scope of this API  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 for the Device location API family
+* 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**.
+* **It is important to note that previous release was done at API family level**
+* **The latest available release for the DeviceLocation API family is 0.2.0-rc1** 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.
+* The release Tag is [r1.1](https://github.com/camaraproject/DeviceLocation/releases/tag/r1.1)
+  * API definition **with inline documentation:**
+  - **location-retrieval v0.1.0**, which is the first alpha release.
+    - OpenAPI [YAML spec file](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)
+
+* **Please note that** the previous release version was at the **device location family level** - it included all three APIs: location-verification, location-retrieval and geofencing. The 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). 
+
+
+## Contributorship and mailing list
+* To subscribe / unsubscribe to the mailing list of this Sub Project and thus be / resign as Contributor please visit <https://lists.camaraproject.org/g/sp-dlo>.
+* A message to all Contributors of this Sub Project can be sent using <[email protected]>.