diff --git a/code/API_definitions/location-retrieval.yaml b/code/API_definitions/location-retrieval.yaml index 41296dbd..d7024380 100644 --- a/code/API_definitions/location-retrieval.yaml +++ b/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: diff --git a/code/API_definitions/location-verification.yaml b/code/API_definitions/location-verification.yaml index 57dd6f1b..d734b209 100644 --- a/code/API_definitions/location-verification.yaml +++ b/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: |