From 64a09d73f9667ce3da1800186d1238cfeb40f33a Mon Sep 17 00:00:00 2001 From: Ludovic Robert <30499179+bigludo7@users.noreply.github.com> Date: Tue, 1 Oct 2024 15:24:03 +0200 Subject: [PATCH 1/5] Update location-retrieval.yaml Add `maxSurface` management --- code/API_definitions/location-retrieval.yaml | 35 +++++++++++++++++--- 1 file changed, 31 insertions(+), 4 deletions(-) diff --git a/code/API_definitions/location-retrieval.yaml b/code/API_definitions/location-retrieval.yaml index a1e09e1..5e5a783 100644 --- a/code/API_definitions/location-retrieval.yaml +++ b/code/API_definitions/location-retrieval.yaml @@ -13,7 +13,9 @@ 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 meters square"). The result accuracy depends on the network's ability and accuracy to locate the device. @@ -42,6 +44,11 @@ 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. + * 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. + # API Functionality @@ -87,7 +94,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 @@ -96,7 +103,7 @@ externalDocs: description: Project documentation at Camara url: https://github.com/camaraproject/DeviceLocation servers: - - url: '{apiRoot}/location-retrieval/v0.3' + - url: '{apiRoot}/location-retrieval/wip' variables: apiRoot: default: http://localhost:9091 @@ -128,6 +135,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 @@ -203,7 +219,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 + 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. @@ -525,6 +545,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: + 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. From d03aa7f1f358a2db69df3d0ff3bb6e5eb9c4e737 Mon Sep 17 00:00:00 2001 From: Ludovic Robert <30499179+bigludo7@users.noreply.github.com> Date: Tue, 1 Oct 2024 16:03:19 +0200 Subject: [PATCH 2/5] Update location-retrieval.yaml Fixing linting + adding precision as suggested by @alpaycetin74: `Note: if both `maxAge` and `maxSurface` requirements fail, the system can either send back one or the other error code. ` --- code/API_definitions/location-retrieval.yaml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/code/API_definitions/location-retrieval.yaml b/code/API_definitions/location-retrieval.yaml index 5e5a783..109d844 100644 --- a/code/API_definitions/location-retrieval.yaml +++ b/code/API_definitions/location-retrieval.yaml @@ -46,8 +46,9 @@ info: * **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. + * absence of `maxSurface` means that "any surface size" is acceptable for the client. * 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 From e767be59e23d0c5f9e4a803129016661cd74612e Mon Sep 17 00:00:00 2001 From: Ludovic Robert <30499179+bigludo7@users.noreply.github.com> Date: Tue, 1 Oct 2024 16:06:09 +0200 Subject: [PATCH 3/5] Update location-retrieval.yaml Fix linting error --- code/API_definitions/location-retrieval.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/code/API_definitions/location-retrieval.yaml b/code/API_definitions/location-retrieval.yaml index 109d844..8de2831 100644 --- a/code/API_definitions/location-retrieval.yaml +++ b/code/API_definitions/location-retrieval.yaml @@ -48,7 +48,7 @@ info: * absence of `maxSurface` means that "any surface size" is acceptable for the client. * 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. + * Note: if both `maxAge` and `maxSurface` requirements fail, the system can either send back one or the other error code. # API Functionality From 30ec4e38bf73da2b43d43424596c2aef58f08560 Mon Sep 17 00:00:00 2001 From: Ludovic Robert <30499179+bigludo7@users.noreply.github.com> Date: Mon, 7 Oct 2024 18:56:24 +0200 Subject: [PATCH 4/5] Update code/API_definitions/location-retrieval.yaml Co-authored-by: Jose Luis Urien --- code/API_definitions/location-retrieval.yaml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/code/API_definitions/location-retrieval.yaml b/code/API_definitions/location-retrieval.yaml index 8de2831..9e4ca22 100644 --- a/code/API_definitions/location-retrieval.yaml +++ b/code/API_definitions/location-retrieval.yaml @@ -15,7 +15,8 @@ info: 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 meters square"). + * 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. From 875025ca0d1a01ba683f7d6d9552601245354ac9 Mon Sep 17 00:00:00 2001 From: Ludovic Robert <30499179+bigludo7@users.noreply.github.com> Date: Tue, 22 Oct 2024 08:37:52 +0200 Subject: [PATCH 5/5] Update location-retrieval.yaml Add a note for maxSurface minimum allowed. --- code/API_definitions/location-retrieval.yaml | 1 + 1 file changed, 1 insertion(+) diff --git a/code/API_definitions/location-retrieval.yaml b/code/API_definitions/location-retrieval.yaml index 9e4ca22..ea5b87f 100644 --- a/code/API_definitions/location-retrieval.yaml +++ b/code/API_definitions/location-retrieval.yaml @@ -48,6 +48,7 @@ info: * **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). * 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.