From 5f19b1c4faf0613816b665028fb7c98842b2f267 Mon Sep 17 00:00:00 2001 From: Maximilian Laue Date: Wed, 8 Jan 2025 11:33:18 +0100 Subject: [PATCH 1/2] feat: decrease the specified minimum of a circle-radius to "1" and add an HTTP-422 if the area cannot be covered by the implementation --- code/API_definitions/geofencing-subscriptions.yaml | 6 ++++-- code/API_definitions/location-verification.yaml | 11 +++++++++-- 2 files changed, 13 insertions(+), 4 deletions(-) diff --git a/code/API_definitions/geofencing-subscriptions.yaml b/code/API_definitions/geofencing-subscriptions.yaml index e845cfec..6a042b2b 100644 --- a/code/API_definitions/geofencing-subscriptions.yaml +++ b/code/API_definitions/geofencing-subscriptions.yaml @@ -737,8 +737,10 @@ components: $ref: "#/components/schemas/Point" radius: type: integer - description: Expected accuracy for the subscription event of device location in m, from location (radius). - minimum: 2000 + description: | + Expected accuracy for the subscription event of device location in m, from location (radius). + Note: The area surface could be restricted locally depending on regulations. Implementations may enforce a larger minimum radius (e.g. 1000 meters). + minimum: 1 maximum: 200000 required: - center diff --git a/code/API_definitions/location-verification.yaml b/code/API_definitions/location-verification.yaml index b33dbeb4..10175353 100644 --- a/code/API_definitions/location-verification.yaml +++ b/code/API_definitions/location-verification.yaml @@ -257,8 +257,10 @@ components: $ref: "#/components/schemas/Point" radius: type: integer - description: Expected accuracy for the verification in meters, from center - minimum: 2000 + description: | + Expected accuracy for the verification in meters, from center. + Note: The area surface could be restricted locally depending on regulations. Implementations may enforce a larger minimum radius (e.g. 1000 meters). + minimum: 1 maximum: 200000 required: - center @@ -573,6 +575,11 @@ components: status: 422 code: LOCATION_VERIFICATION.UNABLE_TO_FULFILL_MAX_AGE message: "Unable to provide expected freshness for location" + GENERIC_422_AREA_NOT_COVERED: + value: + status: 422 + code: AREA_NOT_COVERED + message: The specified area cannot be covered or is too small to be valid 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 3285d90ed351f6ca8c6f9f7f8db929c105f99aca Mon Sep 17 00:00:00 2001 From: Maximilian Laue Date: Wed, 8 Jan 2025 11:49:42 +0100 Subject: [PATCH 2/2] feat: add AREA_NOT_COVERED in location-verification --- .../location-verification.yaml | 76 +++++++++++-------- 1 file changed, 43 insertions(+), 33 deletions(-) diff --git a/code/API_definitions/location-verification.yaml b/code/API_definitions/location-verification.yaml index 10175353..93b04ddf 100644 --- a/code/API_definitions/location-verification.yaml +++ b/code/API_definitions/location-verification.yaml @@ -566,55 +566,65 @@ components: content: application/json: schema: - $ref: "#/components/schemas/ErrorInfo" + allOf: + - $ref: "#/components/schemas/ErrorInfo" + - type: object + properties: + status: + enum: + - 422 + code: + enum: + - AREA_NOT_COVERED + - IDENTIFIER_MISMATCH + - SERVICE_NOT_APPLICABLE + - MISSING_IDENTIFIER + - UNSUPPORTED_IDENTIFIER + - UNNECESSARY_IDENTIFIER + - LOCATION_VERIFICATION.UNABLE_TO_FULFILL_MAX_AGE 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_AREA_NOT_COVERED: value: status: 422 code: AREA_NOT_COVERED message: The specified area cannot be covered or is too small to be valid - 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. + GENERIC_422_IDENTIFIER_MISMATCH: + description: Inconsistency between identifiers not pointing to the same device value: status: 422 - code: UNPROCESSABLE_ENTITY - message: "Value not acceptable: ..." - GENERIC_422_DEVICE_NOT_APPLICABLE: - summary: Service not applicable to the device - description: The provided device is not compatible with the requested operation, according to the service provider rules. + code: IDENTIFIER_MISMATCH + message: Provided identifiers are not consistent. + GENERIC_422_SERVICE_NOT_APPLICABLE: + description: Service not applicable for the provided identifier value: status: 422 - code: DEVICE_NOT_APPLICABLE - message: "The device is not applicable for the requested operation" - GENERIC_422_DEVICE_IDENTIFIERS_MISMATCH: - summary: Device identifiers mismatch - description: Several device identifiers are provided but do not match the same device + code: SERVICE_NOT_APPLICABLE + message: The service is not available for the provided identifier. + GENERIC_422_MISSING_IDENTIFIER: + description: An identifier is not included in the request and the device or phone number identification cannot be derived from the 3-legged access token value: status: 422 - code: DEVICE_IDENTIFIERS_MISMATCH - message: "The provided device identifiers do not match the same device" - GENERIC_422_UNSUPPORTED_DEVICE_IDENTIFIERS: - summary: None of the provided device identifiers is supported by the implementation - description: Message may list the supported device identifiers + code: MISSING_IDENTIFIER + message: The device cannot be identified. + GENERIC_422_UNSUPPORTED_IDENTIFIER: + description: None of the provided identifiers is supported by the implementation value: status: 422 - code: UNSUPPORTED_DEVICE_IDENTIFIERS - message: "Supported device identifiers are: ..." - GENERIC_422_UNIDENTIFIABLE_DEVICE: - summary: No identifier provided - description: No device identifier provided for the device to be located + code: UNSUPPORTED_IDENTIFIER + message: The identifier provided is not supported. + GENERIC_422_UNNECESSARY_IDENTIFIER: + description: An explicit identifier is provided when a device or phone number has already been identified from the access token value: status: 422 - code: UNIDENTIFIABLE_DEVICE - message: "A device must be provided" + code: UNNECESSARY_IDENTIFIER + message: The device is already identified by the access token. + 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" Generic429: description: Too Many Requests