Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update maxAge-behaviour for /verify & /retrieve #218

Merged
merged 8 commits into from
Jul 24, 2024
Merged

Update maxAge-behaviour for /verify & /retrieve #218

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
874d57a
Update `maxAge`-behaviour for `/verify` & `/retrieve`
maxl2287 Jun 21, 2024
98d61f4
fix: change component-name to `VerifyLocationUnprocessableEntity422`
maxl2287 Jun 24, 2024
09a60c1
Update code/API_definitions/location-verification.yaml
maxl2287 Jul 23, 2024
0deb943
fix: update description about when 422 will be thrown
maxl2287 Jul 23, 2024
02b16d7
Merge remote-tracking branch 'refs/remotes/upstream/main' into featur…
maxl2287 Jul 23, 2024
dff561d
style: revert to "" instead of ''
maxl2287 Jul 23, 2024
f6b1610
feat: add 422 examples again
maxl2287 Jul 24, 2024
6a547f1
Update code/API_definitions/location-verification.yaml
jlurien Jul 24, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 6 additions & 2 deletions code/API_definitions/location-retrieval.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -383,7 +383,11 @@ components:
status: 400
code: OUT_OF_RANGE
message: Client specified an invalid range.

GENERIC_400_MAX_AGE_NOT_SATISFIABLE:
value:
status: 400
code: LOCATION_RETRIEVAL.MAXAGE_INVALID_ARGUMENT
message: "maxAge threshold cannot be satisfied"
Generic401:
description: Unauthorized
headers:
Expand Down Expand Up @@ -475,7 +479,7 @@ components:
value:
status: 422
code: LOCATION_RETRIEVAL.UNABLE_TO_FULFILL_MAX_AGE
message: "Unable to provide expected frehsness for location"
message: "Unable to provide expected freshness 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.
Expand Down
27 changes: 20 additions & 7 deletions code/API_definitions/location-verification.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,8 +34,7 @@ info:

* **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.
* maxAge=0 means a fresh calculation is requested by the client. If the system is not able to provide the fresh location, an error 422 with code LOCATION_VERIFICATION.UNABLE_TO_FULFILL_MAX_AGE is sent back.


* **Verification**: Process triggered in the API server to confirm or contradict the expectation assumed by the API client about the device location.
Expand Down Expand Up @@ -86,7 +85,7 @@ paths:
Verify whether the location of a device is within a requested area. The operation returns a verification result and, optionally, a match rate estimation for the location verification in percent.
operationId: verifyLocation
parameters:
- $ref: '#/components/parameters/x-correlator'
- $ref: "#/components/parameters/x-correlator"
requestBody:
required: true
content:
Expand Down Expand Up @@ -126,7 +125,7 @@ paths:
description: Location verification result
headers:
x-correlator:
$ref: '#/components/headers/x-correlator'
$ref: "#/components/headers/x-correlator"
content:
application/json:
schema:
Expand Down Expand Up @@ -171,7 +170,7 @@ paths:
"404":
$ref: "#/components/responses/Generic404"
"422":
$ref: "#/components/responses/Generic422"
$ref: "#/components/responses/VerifyLocationUnprocessableEntity422"
"500":
$ref: "#/components/responses/Generic500"
"503":
Expand Down Expand Up @@ -528,8 +527,8 @@ components:
code: DEVICE_NOT_FOUND
message: "No device found for a provided identifier"

Generic422:
description: Unprocessable entity
VerifyLocationUnprocessableEntity422:
maxl2287 marked this conversation as resolved.
Show resolved Hide resolved
description: Unprocessable Entity
headers:
x-correlator:
$ref: "#/components/headers/x-correlator"
Expand All @@ -538,6 +537,13 @@ components:
schema:
$ref: "#/components/schemas/ErrorInfo"
examples:
LOCATION_VERIFICATION_422_UNABLE_TO_FULFILL_MAX_AGE:
summary: Unable to fulfill maxAge
description: The system is not able to provide the fresh location required by the client
value:
status: 422
code: LOCATION_VERIFICATION.UNABLE_TO_FULFILL_MAX_AGE
message: "Unable to provide expected freshness 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.
Expand Down Expand Up @@ -566,6 +572,13 @@ components:
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
Expand Down