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 location-retrieval with add maxSurface management #262

Open
wants to merge 7 commits into
base: main
Choose a base branch
from
Open

Update location-retrieval with add maxSurface management #262

Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
64a09d7
Update location-retrieval.yaml
bigludo7 Oct 1, 2024
d03aa7f
Update location-retrieval.yaml
bigludo7 Oct 1, 2024
e767be5
Update location-retrieval.yaml
bigludo7 Oct 1, 2024
30ec4e3
Update code/API_definitions/location-retrieval.yaml
bigludo7 Oct 7, 2024
875025c
Update location-retrieval.yaml
bigludo7 Oct 22, 2024
ffb65a8
change line 109 wip to vwip
bigludo7 Dec 17, 2024
8c0763e
Update code/API_definitions/location-retrieval.yaml
bigludo7 Dec 17, 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
38 changes: 34 additions & 4 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,10 @@ info:

The retrieved shape depends on the network conditions at the device'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").
* an accuracy of the localization information by providing a `maxSurface` ("I want a location not larger than 1000000 square meters").


The result accuracy depends on the network's ability and accuracy to locate the device.

Expand Down Expand Up @@ -42,6 +45,13 @@ info:

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

* **Max Surface**: Maximum surface in square meters which is accepted by the client for the location retrieval.

* absence of `maxSurface` means that "any surface size" is acceptable for the client.
* API implementation could specify in the documentation the `maxSurface` minimum acceptable (for exemple minimun of 10000 square meters allowed).
Copy link
Collaborator

Choose a reason for hiding this comment

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

I'd like to propose a minor rewording here, and fixing some typos:
API implementation could specify the minimum acceptable maxSurface in the documentation (for example a minimum of 10000 square meters are allowed).

* If the system is not able to provide an area with a surface acceptable with the client request, an error 422 with code LOCATION_RETRIEVAL.UNABLE_TO_FULFILL_MAX_SURFACE is sent back.
* Note: if both `maxAge` and `maxSurface` requirements fail, the system can either send back one or the other error code.


# API Functionality

Expand Down Expand Up @@ -87,7 +97,7 @@ info:
# Further info and support

(FAQs will be added in a later version of the documentation)
version: 0.3.0
version: wip
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0.html
Expand All @@ -96,7 +106,7 @@ externalDocs:
description: Project documentation at Camara
url: https://github.com/camaraproject/DeviceLocation
servers:
- url: '{apiRoot}/location-retrieval/v0.3'
- url: '{apiRoot}/location-retrieval/vwip'
variables:
apiRoot:
default: http://localhost:9091
Expand Down Expand Up @@ -128,6 +138,15 @@ paths:
device:
phoneNumber: "+123456789"
maxAge: 120
INPUT_PHONE_NUMBER_MAX_AGE_AND_SURFACE:
summary: Phone number, maxAge and maxSurface
description: Retrieve location for a device identified by a phone number, providing a maxAge and maxSurface
value:
device:
phoneNumber: "+123456789"
maxAge: 120
maxSurface: 1000000

INPUT_IP_ADDRESS_V4:
summary: IPv4 address without maxAge
description: Retrieve location for a device identified by an IPv4 address, without an indication for maxAge
Expand Down Expand Up @@ -203,7 +222,11 @@ components:
maxAge:
type: integer
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.

maxSurface:
type: integer
minimum: 1
Copy link
Collaborator

Choose a reason for hiding this comment

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

Not sure what would be realistically the minimum that a "best" implemention may provide, but likely above 100 m2. We may set 1 here and let implementations provide the minimum supported separately.

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

As we allow a min radius of 1 probably we cannot have a min of 100m2. Probably good to add an note indicating that implementations will provide minimum.

description: Maximum surface in square meters which is accepted by the client for the location retrieval. Absence of maxSurface means "any surface size".
example: 1000000
Device:
description: |
End-user equipment able to connect to a mobile network. Examples of devices include smartphones or IoT sensors/actuators.
Expand Down Expand Up @@ -525,6 +548,13 @@ components:
status: 422
code: LOCATION_RETRIEVAL.UNABLE_TO_FULFILL_MAX_AGE
message: "Unable to provide expected freshness for location"
LOCATION_RETRIEVAL_422_UNABLE_TO_FULFILL_MAX_SURFACE:
Copy link
Collaborator

Choose a reason for hiding this comment

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

If the calculated area violates both age and surface conditions, is the implementer free to choose which 422 code to return ?
As an implementation note, we could recommend to check the age condition first because area comparison can require more computation than age comparison.

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

Good point. I've added a note: if both maxAge and maxSurface requirements fail, the system can either send back one or the other error code.

I agree on your recommendation but not sure if we have to add in the yaml as it is more for the system than the client.

summary: Unable to provide expected surface maximum
description: Unable to provide expected surface for location retrieval request
value:
status: 422
code: LOCATION_RETRIEVAL.UNABLE_TO_FULFILL_MAX_SURFACE
message: "Unable to provide requested surface size maximum 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
Loading