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

Adjust maxAge minimum & documentation #188

Merged
merged 15 commits into from
May 7, 2024
Merged

Adjust maxAge minimum & documentation #188

Show file tree
Hide file tree
Changes from 10 commits
Commits
Show all changes
15 commits
Select commit Hold shift + click to select a range
52062c0
Update location-retrieval.yaml
bigludo7 Apr 23, 2024
ffffd2a
Update location-verification.yaml
bigludo7 Apr 23, 2024
d2f694d
Update location-retrieval.yaml
bigludo7 Apr 23, 2024
b47e103
Update location-verification.yaml
bigludo7 Apr 23, 2024
dd519fb
Update location-verification.yaml
bigludo7 Apr 23, 2024
d5f53eb
Update location-verification.yaml
bigludo7 Apr 23, 2024
391a071
Update code/API_definitions/location-verification.yaml
bigludo7 Apr 25, 2024
ace739b
Update location-verification.yaml
bigludo7 Apr 25, 2024
2409c23
Update location-retrieval.yaml
bigludo7 Apr 25, 2024
a3ee755
Update location-verification.yaml
bigludo7 Apr 25, 2024
12741fd
Update location-retrieval.yaml
bigludo7 Apr 26, 2024
2e8350c
Update location-retrieval.yaml
bigludo7 Apr 26, 2024
e9dc94b
Update location-retrieval.yaml
bigludo7 May 3, 2024
b429ae7
Update code/API_definitions/location-verification.yaml
bigludo7 May 6, 2024
cbe5473
Update location-retrieval.yaml
bigludo7 May 6, 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
9 changes: 6 additions & 3 deletions code/API_definitions/location-retrieval.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand All @@ -37,6 +37,10 @@ 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".
bigludo7 marked this conversation as resolved.
Show resolved Hide resolved
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
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".
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".

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@jlurien I have an issue here because in location-retrieval we do not have unknown/UNKNOWN.
We have either

{
  "status": 400,
  "code": "LOCATION_RETRIEVAL.MAXAGE_INVALID_ARGUMENT",
  "message": "maxAge threshold cannot be satisfied"
}

or

{
  "status": 404,
  "code": "NOT_FOUND",
  "message": "The specified resource is not found"
}

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

400 seems a better fit because it specifically points to maxAge. And it applies for all maxAge values, not only 0.
If maxAge was not provided in the request (any age is acceptible), but the system still cannot find a location, 404 can be used.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks @alpaycetin74
Works for me and I can update the documentation accordingly.
If not able to provide require freshness (maxAge filled) --> 400 + code LOCATION_RETRIEVAL.MAXAGE_INVALID_ARGUMENT
If not able to provide any location for a request without maxAge --> 404

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Right, I didn't realize that.
Regarding errors, to me 400 is for cases when the provided input does not comply with the schema or some constraint that should be known by the client, independently of the device. It could fit for cases where some implementation does not support maxAge=0 for any user (it is still pending how to provide information about limits of the implementation to the client). But for cases where the maxAge cannot be satisfied for a specific device or at a specific moment, I think it is more of a 404 or even 422 (the entity combining device and maxAge is not processable by the system).

These RESTful interpretations of HTTP statuses are very subtle anyway.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For (2) I think 404 is more natural, the (3) is more about the combination of device + maxAge at a given time

(1)If maxAge input does not fit the pattern (like 5fr/"3) --> 400
(2)If not able to locate the mobile --> 404 with code LOCATION_RETRIEVAL.DEVICE_NOT_FOUND
(3)If not able to provide expected freshness --> 422 with a code LOCATION_RETRIEVAL.UNABLE_TO_FULFILL_MAX_AGE

cc @javier-carrocalabor

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Another difference with location-verification is that in this case we cannot return a lastLocationTime indicating how old is the more recent location

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

hello @bigludo7 ,

  • is maxAge parameter absent in case (2) ?
  • in case (3), there is a maxAge parameter for sure, and it can also be 0, am I right ?
    Thank you.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hello @alpaycetin74

is maxAge parameter absent in case (2) ?
Humm.. It is fair to assume that yes.

in case (3), there is a maxAge parameter for sure, and it can also be 0, am I right ?
Yes - no doubt for this one !

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks @bigludo7 ,
if I may summarize my view:

For location retrieval,
(1) Obviously a client error, 400 is appropriate.
It is possible to advise LOCATION_RETRIEVAL.MAXAGE_INVALID_ARGUMENT, but the implementer may not have full control over error messages created in case of syntactic errors - those may be created by software libraries.
(2) No location available, even if maxAge is absent (infinite).
404 with code LOCATION_RETRIEVAL.DEVICE_NOT_FOUND is appropriate.
(3) maxAge condition (including 0) cannot be satisfied.
422 with code LOCATION_RETRIEVAL.UNABLE_TO_FULFILL_MAX_AGE is appropriate.

For location verification,
(1) same
(2) UNKNOWN without lastLocationTime
(3) UNKNOWN, may have lastLocationTime if system has it.
Thank you

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This line has to be modified in any case, as the API cannot response "unknown"


* **Last Location Time** : Last date and time when the device was localized.


Expand Down Expand Up @@ -146,8 +150,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

Expand Down
9 changes: 7 additions & 2 deletions code/API_definitions/location-verification.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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".
bigludo7 marked this conversation as resolved.
Show resolved Hide resolved


* **Verification**: Process triggered in the API server to confirm or contradict the expectation assumed by the API client about the device location.

# API Functionality
Expand Down Expand Up @@ -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: |
Expand Down