Adjust maxAge minimum & documentation

code/API_definitions/location-retrieval.yaml

@@ -13,7 +13,7 @@ info:
 
     The retrieved shape depends on the network conditions at the subscriber's location and any of the supported shapes could be received.
 
-    The requester could optionally ask for a freshness of the localization information by providing a maxAge ("I want a location not older than 600 seconds")
+    The requester could optionally ask for a freshness of the localization information by providing a maxAge ("I want a location not older than 600 seconds").
 
     The result accuracy depends on the network's ability and accuracy to locate the device.
 
@@ -37,6 +37,9 @@ 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. If the system is not able to provide location a error 404 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 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.
 
 
@@ -112,7 +115,9 @@ paths:
         '403':
           $ref: '#/components/responses/Generic403'
         '404':
-          $ref: '#/components/responses/Generic404'
+          $ref: '#/components/responses/RetrieveLocationNotFound404'
+        '422':
+          $ref: '#/components/responses/RetrieveLocationUnprocessableEntity422'
         '500':
           $ref: '#/components/responses/Generic500'
         '503':
@@ -146,8 +151,7 @@ components:
           $ref: '#/components/schemas/Device'
         maxAge:
           type: integer
-          description: Maximum age of the location information which is accepted for the location retrieval (in seconds)
-          minimum: 60
+          description: Maximum age of the location information which is accepted for the location retrieval (in seconds). Absence of maxAge means "any age" and maxAge=0 means a fresh calculation.
       required:
         - device
 
@@ -393,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'
+    RetrieveLocationUnprocessableEntity422:
+      description: Unprocessable Entity
       headers:
         x-correlator:
           $ref: '#/components/headers/x-correlator'
@@ -403,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:

code/API_definitions/location-verification.yaml

@@ -32,6 +32,12 @@ 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 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 checked at that time for any reason, the API response will be "UNKNOWN" and the `lastLocationTime` attribute may indicate the last available time for the device location.
+
+
     * **Verification**: Process triggered in the API server to confirm or contradict the expectation assumed by the API client about the device location.
 
     # API Functionality
@@ -355,9 +361,8 @@ components:
       example: 2001:db8:85a3:8d3:1319:8a2e:370:7344
 
     MaxAge:
-      description: The maximum age (in seconds) of the available location, which is accepted for the verification.
+      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
-      minimum: 60
       example: 120
     VerificationResult:
       description: |