Update location-retrieval.yaml

Aligned following our discussion
camaraproject · Apr 26, 2024 · 12741fd · 12741fd
1 parent a3ee755
commit 12741fd
Showing 1 changed file with 29 additions and 8 deletions.
diff --git a/code/API_definitions/location-retrieval.yaml b/code/API_definitions/location-retrieval.yaml
@@ -37,9 +37,8 @@ info:
 
     * **Max Age**: Maximum age of the location information which is accepted for the location retrieval (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 may still return lastLocationTime, if available.
-      * maxAge=0 means a fresh calculation is requested by the client.
-      If the system does not support it, or fresh location cannot be calculated at that time for any reason, the API response will be "unknown".
+      * 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. If the system is not able to provide location a error 400 with code LOCATION_RETRIEVAL.DEVICE_NOT_FOUND is send back. 
+      * maxAge=0 means a fresh calculation is requested by the client. If the system is not able to provide fresh location (current time - location time > maxDate) an error 422 with code LOCATION_RETRIEVAL.UNABLE_TO_FULFILL_MAX_AGE is send back.
 
     * **Last Location Time** : Last date and time when the device was localized.
 
@@ -116,7 +115,9 @@ paths:
         '403':
           $ref: '#/components/responses/Generic403'
         '404':
-          $ref: '#/components/responses/Generic404'
+          $ref: '#/components/responses/RetrieveLocationNotFound404'
+        '422':
+          $ref: '#/components/responses/RetrieveLocationUnprocessableEntity404'
         '500':
           $ref: '#/components/responses/Generic500'
         '503':
@@ -396,8 +397,28 @@ components:
             status: 403
             code: PERMISSION_DENIED
             message: "Operation not allowed: ..."
-    Generic404:
+    RetrieveLocationNotFound404:
       description: Not found
+      headers:
+        x-correlator:
+          $ref: '#/components/headers/x-correlator'
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/ErrorInfo'
+          examples:
+            notFound:
+              value:
+                status: 404
+                code: NOT_FOUND
+                message: 'The specified resource is not found'
+            deviceNotFound:
+              value:
+                status: 404
+                code: LOCATION_RETRIEVAL.DEVICE_NOT_FOUND
+                message: 'The location server is not able to locate the mobile'
+    RetrieveLocationUnprocessableEntity404:
+      description: Unprocessable Entity
       headers:
         x-correlator:
           $ref: '#/components/headers/x-correlator'
@@ -406,9 +427,9 @@ components:
           schema:
             $ref: '#/components/schemas/ErrorInfo'
           example:
-            status: 404
-            code: NOT_FOUND
-            message: 'The specified resource is not found'
+            status: 422
+            code: LOCATION_RETRIEVAL.UNABLE_TO_FULFILL_MAX_AGE
+            message: "Unable to provide expected frehsness for location"
     Generic500:
       description: Internal server error
       headers: