diff --git a/code/API_definitions/location-retrieval.yaml b/code/API_definitions/location-retrieval.yaml index 80131db5..74b15af3 100644 --- a/code/API_definitions/location-retrieval.yaml +++ b/code/API_definitions/location-retrieval.yaml @@ -62,6 +62,7 @@ info: * a timestamp with the location information freshness. + # Authorization and authentication The "Camara Security and Interoperability Profile" provides details of how an API consumer requests an access token. Please refer to Identity and Consent Management (https://github.com/camaraproject/IdentityAndConsentManagement/) for the released version of the profile. @@ -72,6 +73,7 @@ info: + # Identifying the device from the access token This API requires the API consumer to identify a device as the subject of the API as follows: @@ -102,16 +104,18 @@ info: - Check with the API provider whether a unique "secondary" phone number is already associated with each device and use the secondary phone number to identify the intended device if available. + # Additional CAMARA error responses The list of error codes in this API specification is not exhaustive. Therefore the API specification MAY not document some non-mandatory error statuses as indicated in `CAMARA API Design Guide`. - Please refer to the `CAMARA_common.yaml` of the Commonalities Release associated to this API version for a complete list of error responses. The applicable Commonalities Release can be identified in the `API Readiness Checklist` document associated to this API version. + Please refer to the `CAMARA_common.yaml` of the Commonalities Release associated to this API version for a complete list of error responses. The applicable Commonalities Release can be identified from the `x-camara-commonalities` field, the changelog and the metadata of the released API version. As a specific rule, error `501 - NOT_IMPLEMENTED` can be only a possible error response if it is explicitly documented in the API. + # Request body strictness This API rejects requests with JSON request bodies that contain properties not declared in this specification, at any nesting level. Unknown properties result in a `400 INVALID_ARGUMENT` response. @@ -124,7 +128,7 @@ info: license: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0.html - x-camara-commonalities: 0.8.0 + x-camara-commonalities: 0.9.0 externalDocs: description: Product documentation at CAMARA url: https://github.com/camaraproject/DeviceLocation @@ -209,13 +213,13 @@ paths: LOCATION_CIRCLE_WITH_DEVICE: $ref: "#/components/examples/LOCATION_CIRCLE_WITH_DEVICE" '400': - $ref: '../common/CAMARA_common.yaml#/components/responses/Generic400' + $ref: '../common/CAMARA_common.yaml#/components/responses/BadRequestWithRange400' '401': - $ref: '../common/CAMARA_common.yaml#/components/responses/Generic401' + $ref: '../common/CAMARA_common.yaml#/components/responses/Unauthenticated401' '403': - $ref: '#/components/responses/Generic403' + $ref: '../common/CAMARA_common.yaml#/components/responses/PermissionDenied403' '404': - $ref: '#/components/responses/RetrieveLocationNotFound404' + $ref: '../common/CAMARA_common.yaml#/components/responses/IdentifierNotFound404' '422': $ref: '#/components/responses/RetrieveLocationUnprocessableEntity422' security: @@ -248,36 +252,12 @@ components: maximum: 2147483647 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: - $ref: '../common/CAMARA_common.yaml#/components/schemas/Device' - DeviceResponse: $ref: '../common/CAMARA_common.yaml#/components/schemas/DeviceResponse' Area: $ref: '../common/CAMARA_common.yaml#/components/schemas/Area' - AreaType: - $ref: '../common/CAMARA_common.yaml#/components/schemas/AreaType' - - Circle: - $ref: '../common/CAMARA_common.yaml#/components/schemas/Circle' - - Polygon: - $ref: '../common/CAMARA_common.yaml#/components/schemas/Polygon' - - PointList: - $ref: '../common/CAMARA_common.yaml#/components/schemas/PointList' - - Point: - $ref: '../common/CAMARA_common.yaml#/components/schemas/Point' - - Latitude: - $ref: '../common/CAMARA_common.yaml#/components/schemas/Latitude' - - Longitude: - $ref: '../common/CAMARA_common.yaml#/components/schemas/Longitude' - Location: type: object description: Device location @@ -300,58 +280,6 @@ components: example: "2023-09-07T10:40:52Z" responses: - Generic403: - description: Forbidden - headers: - x-correlator: - $ref: '../common/CAMARA_common.yaml#/components/headers/x-correlator' - content: - application/json: - schema: - allOf: - - $ref: '../common/CAMARA_common.yaml#/components/schemas/ErrorInfo' - - type: object - properties: - status: - enum: - - 403 - code: - enum: - - PERMISSION_DENIED - examples: - GENERIC_403_PERMISSION_DENIED: - summary: Permission denied - description: Permission denied. OAuth2 token access does not have the required scope or when the user fails operational security - value: - status: 403 - code: PERMISSION_DENIED - message: Client does not have sufficient permissions to perform this action. - RetrieveLocationNotFound404: - description: Not found - headers: - x-correlator: - $ref: '../common/CAMARA_common.yaml#/components/headers/x-correlator' - content: - application/json: - schema: - allOf: - - $ref: '../common/CAMARA_common.yaml#/components/schemas/ErrorInfo' - - type: object - properties: - status: - enum: - - 404 - code: - enum: - - IDENTIFIER_NOT_FOUND - examples: - GENERIC_404_IDENTIFIER_NOT_FOUND: - summary: Identifier not found - description: Some identifier cannot be matched to a device - value: - status: 404 - code: IDENTIFIER_NOT_FOUND - message: Device identifier not found. RetrieveLocationUnprocessableEntity422: description: Unprocessable Content headers: @@ -378,33 +306,13 @@ components: - LOCATION_RETRIEVAL.UNABLE_TO_LOCATE examples: GENERIC_422_SERVICE_NOT_APPLICABLE: - summary: Service not applicable - description: Service not applicable for the provided identifier - value: - status: 422 - code: SERVICE_NOT_APPLICABLE - message: The service is not available for the provided identifier. - GENERIC_422_MISSING_IDENTIFIER: - summary: 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: MISSING_IDENTIFIER - message: The device cannot be identified. - GENERIC_422_UNSUPPORTED_IDENTIFIER: - summary: Unsupported identifier - description: None of the provided identifiers is supported by the implementation - value: - status: 422 - code: UNSUPPORTED_IDENTIFIER - message: The identifier provided is not supported. - GENERIC_422_UNNECESSARY_IDENTIFIER: - summary: 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: UNNECESSARY_IDENTIFIER - message: The device is already identified by the access token. + $ref: '../common/CAMARA_common.yaml#/components/examples/GENERIC_422_SERVICE_NOT_APPLICABLE' + GENERIC_422_MISSING_IDENTIFIER_DEVICE: + $ref: '../common/CAMARA_common.yaml#/components/examples/GENERIC_422_MISSING_IDENTIFIER_DEVICE' + GENERIC_422_UNSUPPORTED_IDENTIFIER_DEVICE: + $ref: '../common/CAMARA_common.yaml#/components/examples/GENERIC_422_UNSUPPORTED_IDENTIFIER_DEVICE' + GENERIC_422_UNNECESSARY_IDENTIFIER_DEVICE: + $ref: '../common/CAMARA_common.yaml#/components/examples/GENERIC_422_UNNECESSARY_IDENTIFIER_DEVICE' LOCATION_RETRIEVAL_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 diff --git a/code/API_definitions/location-verification.yaml b/code/API_definitions/location-verification.yaml index 9c1d54be..0cb7cffb 100644 --- a/code/API_definitions/location-verification.yaml +++ b/code/API_definitions/location-verification.yaml @@ -46,6 +46,7 @@ info: - Verify whether the device location is within a requested area, currently a circle with center specified by the latitude and longitude, and radius specified by the accuracy. The operation returns a verification result and, optionally, a match rate estimation for the location verification in percent. + # Authorization and authentication The "Camara Security and Interoperability Profile" provides details of how an API consumer requests an access token. Please refer to Identity and Consent Management (https://github.com/camaraproject/IdentityAndConsentManagement/) for the released version of the profile. @@ -56,6 +57,7 @@ info: + # Identifying the device from the access token This API requires the API consumer to identify a device as the subject of the API as follows: @@ -86,16 +88,18 @@ info: - Check with the API provider whether a unique "secondary" phone number is already associated with each device and use the secondary phone number to identify the intended device if available. + # Additional CAMARA error responses The list of error codes in this API specification is not exhaustive. Therefore the API specification MAY not document some non-mandatory error statuses as indicated in `CAMARA API Design Guide`. - Please refer to the `CAMARA_common.yaml` of the Commonalities Release associated to this API version for a complete list of error responses. The applicable Commonalities Release can be identified in the `API Readiness Checklist` document associated to this API version. + Please refer to the `CAMARA_common.yaml` of the Commonalities Release associated to this API version for a complete list of error responses. The applicable Commonalities Release can be identified from the `x-camara-commonalities` field, the changelog and the metadata of the released API version. As a specific rule, error `501 - NOT_IMPLEMENTED` can be only a possible error response if it is explicitly documented in the API. + # Request body strictness This API rejects requests with JSON request bodies that contain properties not declared in this specification, at any nesting level. Unknown properties result in a `400 INVALID_ARGUMENT` response. @@ -108,7 +112,7 @@ info: license: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0.html - x-camara-commonalities: 0.8.0 + x-camara-commonalities: 0.9.0 externalDocs: description: Product documentation at CAMARA url: https://github.com/camaraproject/DeviceLocation @@ -232,13 +236,13 @@ paths: matchRate: 74 lastLocationTime: "2023-09-07T10:40:52Z" "400": - $ref: "../common/CAMARA_common.yaml#/components/responses/Generic400" + $ref: "../common/CAMARA_common.yaml#/components/responses/BadRequestWithRange400" "401": - $ref: "../common/CAMARA_common.yaml#/components/responses/Generic401" + $ref: "../common/CAMARA_common.yaml#/components/responses/Unauthenticated401" "403": - $ref: "#/components/responses/Generic403" + $ref: "../common/CAMARA_common.yaml#/components/responses/PermissionDenied403" "404": - $ref: "#/components/responses/VerifyLocationNotFound404" + $ref: "../common/CAMARA_common.yaml#/components/responses/IdentifierNotFound404" "422": $ref: "#/components/responses/VerifyLocationUnprocessableEntity422" security: @@ -360,58 +364,6 @@ components: example: "2023-09-07T10:40:52Z" responses: - Generic403: - description: Forbidden - headers: - x-correlator: - $ref: "../common/CAMARA_common.yaml#/components/headers/x-correlator" - content: - application/json: - schema: - allOf: - - $ref: "../common/CAMARA_common.yaml#/components/schemas/ErrorInfo" - - type: object - properties: - status: - enum: - - 403 - code: - enum: - - PERMISSION_DENIED - examples: - GENERIC_403_PERMISSION_DENIED: - description: Permission denied. OAuth2 token access does not have the required scope or when the user fails operational security - value: - status: 403 - code: PERMISSION_DENIED - message: Client does not have sufficient permissions to perform this action. - - VerifyLocationNotFound404: - description: Not found - headers: - x-correlator: - $ref: "../common/CAMARA_common.yaml#/components/headers/x-correlator" - content: - application/json: - schema: - allOf: - - $ref: "../common/CAMARA_common.yaml#/components/schemas/ErrorInfo" - - type: object - properties: - status: - enum: - - 404 - code: - enum: - - IDENTIFIER_NOT_FOUND - examples: - GENERIC_404_IDENTIFIER_NOT_FOUND: - description: Some identifier cannot be matched to a device - value: - status: 404 - code: IDENTIFIER_NOT_FOUND - message: Device identifier not found. - VerifyLocationUnprocessableEntity422: description: Unprocessable Content headers: @@ -439,29 +391,13 @@ components: - LOCATION_VERIFICATION.UNABLE_TO_LOCATE examples: GENERIC_422_SERVICE_NOT_APPLICABLE: - description: Service not applicable for the provided identifier - value: - status: 422 - 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: 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_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: UNNECESSARY_IDENTIFIER - message: The device is already identified by the access token. + $ref: "../common/CAMARA_common.yaml#/components/examples/GENERIC_422_SERVICE_NOT_APPLICABLE" + GENERIC_422_MISSING_IDENTIFIER_DEVICE: + $ref: "../common/CAMARA_common.yaml#/components/examples/GENERIC_422_MISSING_IDENTIFIER_DEVICE" + GENERIC_422_UNSUPPORTED_IDENTIFIER_DEVICE: + $ref: "../common/CAMARA_common.yaml#/components/examples/GENERIC_422_UNSUPPORTED_IDENTIFIER_DEVICE" + GENERIC_422_UNNECESSARY_IDENTIFIER_DEVICE: + $ref: "../common/CAMARA_common.yaml#/components/examples/GENERIC_422_UNNECESSARY_IDENTIFIER_DEVICE" LOCATION_VERIFICATION_422_AREA_NOT_COVERED: summary: The area cannot be covered description: The system is not able cover the requested area diff --git a/code/Test_definitions/location-retrieval.feature b/code/Test_definitions/location-retrieval.feature index d49276e2..337ed807 100644 --- a/code/Test_definitions/location-retrieval.feature +++ b/code/Test_definitions/location-retrieval.feature @@ -98,11 +98,11 @@ Feature: CAMARA Device location retrieval API, vwip - Operation retrieveLocation And the response property "$.message" contains a user friendly text Examples: - | device_identifier | oas_spec_schema | - | $.device.phoneNumber | /components/schemas/PhoneNumber | - | $.device.ipv4Address | /components/schemas/DeviceIpv4Addr | - | $.device.ipv6Address | /components/schemas/DeviceIpv6Address | - | $.device.networkAccessIdentifier | /components/schemas/NetworkAccessIdentifier | + | device_identifier | oas_spec_schema | + | $.device.phoneNumber | #/components/schemas/PhoneNumber | + | $.device.ipv4Address | #/components/schemas/DeviceIpv4Address | + | $.device.ipv6Address | #/components/schemas/DeviceIpv6Address | + | $.device.networkAccessIdentifier | #/components/schemas/NetworkAccessIdentifier | @location_retrieval_C01.03_device_not_found Scenario: Some identifier cannot be matched to a device @@ -182,7 +182,7 @@ Feature: CAMARA Device location retrieval API, vwip - Operation retrieveLocation @location_retrieval_400.2_other_input_properties_schema_not_compliant Scenario Outline: Input property values do not comply with the schema - Given the request body property "" does not comply with the OAS schema at + Given the request body property "" does not comply with the OAS schema at "" When the request "retrieveLocation" is sent Then the response status code is 400 And the response property "$.status" is 400 @@ -190,13 +190,13 @@ Feature: CAMARA Device location retrieval API, vwip - Operation retrieveLocation And the response property "$.message" contains a user friendly text Examples: - | input_property | oas_spec_schema | - | $.maxAge | /components/schemas/RetrievalLocationRequest/properties/maxAge | - | $.maxSurface | /components/schemas/RetrievalLocationRequest/properties/maxSurface | + | input_property | oas_spec_schema | + | $.maxAge | #/components/schemas/RetrievalLocationRequest/properties/maxAge | + | $.maxSurface | #/components/schemas/RetrievalLocationRequest/properties/maxSurface | @location_retrieval_400.3_invalid_x-correlator Scenario: Invalid x-correlator value - Given the header "x-correlator" does not comply with the OAS schema at "/components/schemas/XCorrelator" + Given the header "x-correlator" does not comply with the OAS schema at "#/components/schemas/XCorrelator" When the request "retrieveLocation" is sent Then the response status code is 400 And the response property "$.status" is 400 diff --git a/code/Test_definitions/location-verification.feature b/code/Test_definitions/location-verification.feature index 731874ae..08d81304 100644 --- a/code/Test_definitions/location-verification.feature +++ b/code/Test_definitions/location-verification.feature @@ -33,7 +33,7 @@ Feature: CAMARA Device location verification API, vwip - Operation verifyLocatio And the response header "Content-Type" is "application/json" And the response header "x-correlator" has same value as the request header "x-correlator" # The response has to comply with the generic response schema which is part of the spec - And the response body complies with the OAS schema at "/components/schemas/VerifyLocationResponse" + And the response body complies with the OAS schema at "#/components/schemas/VerifyLocationResponse" # Additionally any success response has to comply with some constraints not documented in the schema And the response property "$.matchRate" exists only if "$.verificationResult" is "PARTIAL" @@ -48,7 +48,7 @@ Feature: CAMARA Device location verification API, vwip - Operation verifyLocatio Then the response status code is 200 And the response header "Content-Type" is "application/json" And the response header "x-correlator" has same value as the request header "x-correlator" - And the response body complies with the OAS schema at "/components/schemas/VerifyLocationResponse" + And the response body complies with the OAS schema at "#/components/schemas/VerifyLocationResponse" And the response property "$.verificationResult" is one of: ["TRUE", "PARTIAL"] And the response property "$.lastLocationTime" exists And the response property "$.matchRate" exists only if "$.verificationResult" is "PARTIAL" @@ -62,7 +62,7 @@ Feature: CAMARA Device location verification API, vwip - Operation verifyLocatio Then the response status code is 200 And the response header "Content-Type" is "application/json" And the response header "x-correlator" has same value as the request header "x-correlator" - And the response body complies with the OAS schema at "/components/schemas/VerifyLocationResponse" + And the response body complies with the OAS schema at "#/components/schemas/VerifyLocationResponse" And the response property "$.verificationResult" is one of: ["TRUE", "PARTIAL"] And the response property "$.matchRate" exists only if "$.verificationResult" is "PARTIAL" And the response property "$.lastLocationTime" value is not older than the value of "$.maxAge" in the request @@ -75,7 +75,7 @@ Feature: CAMARA Device location verification API, vwip - Operation verifyLocatio Then the response status code is 200 And the response header "Content-Type" is "application/json" And the response header "x-correlator" has same value as the request header "x-correlator" - And the response body complies with the OAS schema at "/components/schemas/VerifyLocationResponse" + And the response body complies with the OAS schema at "#/components/schemas/VerifyLocationResponse" And the response property "$.verificationResult" is "FALSE" And the response property "$.lastLocationTime" exists And the response property "$.matchRate" does not exist @@ -91,9 +91,9 @@ Feature: CAMARA Device location verification API, vwip - Operation verifyLocatio Then the response status code is 200 And the response header "Content-Type" is "application/json" And the response header "x-correlator" has same value as the request header "x-correlator" - And the response body complies with the OAS schema at "/components/schemas/VerifyLocationResponse" + And the response body complies with the OAS schema at "#/components/schemas/VerifyLocationResponse" And the response property "$.device" exists - And the response property "$.device" complies with the OAS schema at "/components/schemas/DeviceResponse" + And the response property "$.device" complies with the OAS schema at "#/components/schemas/DeviceResponse" # Error scenarios for management of input parameter device @@ -118,11 +118,11 @@ Feature: CAMARA Device location verification API, vwip - Operation verifyLocatio And the response property "$.message" contains a user friendly text Examples: - | device_identifier | oas_spec_schema | - | $.device.phoneNumber | /components/schemas/PhoneNumber | - | $.device.ipv4Address | /components/schemas/DeviceIpv4Addr | - | $.device.ipv6Address | /components/schemas/DeviceIpv6Address | - | $.device.networkAccessIdentifier | /components/schemas/NetworkAccessIdentifier | + | device_identifier | oas_spec_schema | + | $.device.phoneNumber | #/components/schemas/PhoneNumber | + | $.device.ipv4Address | #/components/schemas/DeviceIpv4Address | + | $.device.ipv6Address | #/components/schemas/DeviceIpv6Address | + | $.device.networkAccessIdentifier | #/components/schemas/NetworkAccessIdentifier | # This scenario may happen e.g. with 2-legged access tokens, which do not identify a single device. @location_verification_C01.03_device_not_found @@ -200,7 +200,7 @@ Feature: CAMARA Device location verification API, vwip - Operation verifyLocatio @location_verification_400.3_other_input_properties_schema_not_compliant # Test other input properties in addition to device Scenario Outline: Input property values do not comply with the schema - Given the request body property "" does not comply with the OAS schema at + Given the request body property "" does not comply with the OAS schema at "" When the request "verifyLocation" is sent Then the response status code is 400 And the response property "$.status" is 400 @@ -208,12 +208,12 @@ Feature: CAMARA Device location verification API, vwip - Operation verifyLocatio And the response property "$.message" contains a user friendly text Examples: - | input_property | oas_spec_schema | - | $.area.areaType | /components/schemas/AreaType | - | $.area.center.latitude | /components/schemas/Latitude | - | $.area.center.longitude | /components/schemas/Longitude | - | $.area.radius | /components/schemas/Circle/allOf/1/properties/radius | - | $.maxAge | /components/schemas/MaxAge | + | input_property | oas_spec_schema | + | $.area.areaType | #/components/schemas/AreaType | + | $.area.center.latitude | #/components/schemas/Latitude | + | $.area.center.longitude | #/components/schemas/Longitude | + | $.area.radius | #/components/schemas/Circle/allOf/1/properties/radius | + | $.maxAge | #/components/schemas/MaxAge | @location_verification_400.4_required_input_properties_missing Scenario Outline: Required input properties are missing @@ -235,7 +235,7 @@ Feature: CAMARA Device location verification API, vwip - Operation verifyLocatio @location_verification_400.5_invalid_x-correlator Scenario: Invalid x-correlator value - Given the header "x-correlator" does not comply with the OAS schema at "/components/schemas/XCorrelator" + Given the header "x-correlator" does not comply with the OAS schema at "#/components/schemas/XCorrelator" When the request "verifyLocation" is sent Then the response status code is 400 And the response property "$.status" is 400