diff --git a/code/API_definitions/population-density-data.yaml b/code/API_definitions/population-density-data.yaml index 2b9bd58..540fbf4 100644 --- a/code/API_definitions/population-density-data.yaml +++ b/code/API_definitions/population-density-data.yaml @@ -44,6 +44,16 @@ info: When an asynchronous response is requested, the 202 response of the API will include an `operationId` property. This `operationId` property will also be sent in the callback notification. The purpose of the `operationId` is to correlate an asynchronous response with its corresponding request. + Using `credentialType: PRIVATE_KEY_JWT` requires the JWT authentication parameters to be pre-configured + out-of-band between the API consumer and the API provider as part of the onboarding process. No response of + this API returns `sinkCredential`, so the provider's `jwksUri` is never conveyed in-band. Unlike an event + subscription, this operation creates no resource to read back, the same static `jwksUri` would be repeated on + every `202` response, and the callback may be delivered before the API consumer has processed that response. + If `PRIVATE_KEY_JWT` is requested and no JWK Set is configured for the API consumer, the API returns the + error response `422 PRIVATE_KEY_JWT_NOT_CONFIGURED`. A failure to authenticate against the API consumer's + authorization server when the callback is delivered cannot be detected while the request is being processed, + and is therefore reported in the callback with property `status` set to `OPERATION_NOT_COMPLETED`. + # API Functionality Once a developer specifies (1) the area (either as a polygon shape or as a list of geohashes), @@ -102,7 +112,7 @@ info: The standard behaviour of the API is synchronous, although for large area requests the API may behave asynchronously. An API invoker can enforce asynchronous behaviour by providing a callback URL (`sink`) - is in the request, in this case the API sends a callback + in the request, in this case the API sends a callback to the callback URL provided with the result of the request. If `sink` is included, it is RECOMMENDED for the client to provide as well the `sinkCredential` property to protect the notification endpoint. In the current version,`sinkCredential.credentialType` @@ -142,8 +152,8 @@ info: In cases where personal data is processed by the API and users can exercise their rights through mechanisms such as opt-in and/or opt-out, the use of three-legged access tokens is mandatory. This ensures that the API remains in compliance with privacy regulations, upholding the principles of transparency and user-centric privacy-by-design. - Population Density Data API ensures the usage of anonymized information and do not treat personal data neither as input nor output. - Therefore, the access to Population Density Data API is defined as Client Credentials - 2-legged. Please refer to Identify and Consent Management (https://github.com/camaraproject/IdentityAndConsentManagement/) for the latest detailed specification of this authentication/authorization flow. + Population Density Data API ensures the usage of anonymized information and does not treat personal data as either input or output. + Therefore, the access to Population Density Data API is defined as Client Credentials - 2-legged. Please refer to Identity and Consent Management (https://github.com/camaraproject/IdentityAndConsentManagement/) for the latest detailed specification of this authentication/authorization flow. # Additional CAMARA error responses @@ -578,6 +588,7 @@ components: - Indicated `endTime` is earlier than the `startTime` ("code": "POPULATION_DENSITY_DATA.INVALID_END_TIME", "message": "Indicated endTime is earlier than the startTime") - Indicated time period is partially in the past and partially in the future ("code": "POPULATION_DENSITY_DATA.INVALID_TIME_PERIOD", "message": "time period is partially in the past and partially in the future") - Indicated time period is greater than the maximum allowed (More than maximum hours between startTime and endTime) ("code": "POPULATION_DENSITY_DATA.MAX_TIME_PERIOD_EXCEEDED", "message": "Indicated time period is greater than the maximum allowed (More than maximum hours between startTime and endTime)") + - `sinkCredential.credentialType` is set to `PRIVATE_KEY_JWT` but no JWK Set is configured for the API consumer ("code": "PRIVATE_KEY_JWT_NOT_CONFIGURED", "message": "No JWK Set configured for PRIVATE_KEY_JWT authentication.") headers: x-correlator: $ref: '../common/CAMARA_common.yaml#/components/headers/x-correlator' @@ -603,6 +614,7 @@ components: - POPULATION_DENSITY_DATA.INVALID_END_TIME - POPULATION_DENSITY_DATA.MAX_TIME_PERIOD_EXCEEDED - POPULATION_DENSITY_DATA.INVALID_TIME_PERIOD + - PRIVATE_KEY_JWT_NOT_CONFIGURED examples: GENERIC_400_INVALID_ARGUMENT: value: @@ -610,10 +622,11 @@ components: code: INVALID_ARGUMENT message: Invalid input GENERIC_400_INVALID_CREDENTIAL: + description: Invalid sink credential type value: status: 400 code: INVALID_CREDENTIAL - message: "Only Access token is supported" + message: Only Access token or Private key JWT are supported GENERIC_400_INVALID_TOKEN: value: status: 400 @@ -687,6 +700,7 @@ components: - POPULATION_DENSITY_DATA.UNSUPPORTED_PRECISION - POPULATION_DENSITY_DATA.UNSUPPORTED_SYNC_RESPONSE - POPULATION_DENSITY_DATA.UNSUPPORTED_AREA_TYPE + - PRIVATE_KEY_JWT_NOT_CONFIGURED examples: POPULATION_DENSITY_DATA_422_UNSUPPORTED_REQUEST: value: @@ -711,6 +725,12 @@ components: status: 422 code: POPULATION_DENSITY_DATA.UNSUPPORTED_AREA_TYPE message: The requested areaType is not supported by the MNO + GENERIC_422_PRIVATE_KEY_JWT_NOT_CONFIGURED: + description: Private key JWT sink credential type is used but no configuration was pre-shared + value: + status: 422 + code: PRIVATE_KEY_JWT_NOT_CONFIGURED + message: No JWK Set configured for PRIVATE_KEY_JWT authentication. examples: PopulationDensitySupportedAreaResponseExample: description: Population density supported area response example diff --git a/code/Test_definitions/population-density-data.feature b/code/Test_definitions/population-density-data.feature index 776a7a0..b5cd882 100644 --- a/code/Test_definitions/population-density-data.feature +++ b/code/Test_definitions/population-density-data.feature @@ -155,7 +155,7 @@ Feature: CAMARA Population Density Data API, vwip 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 includes property "$.operationId" - And there have been some problem processing the request asynchronously + And there has been a problem processing the request asynchronously And the request with the response body will be received at the address of the request property "$.sink" with property "$.operationId" equal to response property "$.operationId" And the request will have header "Authorization" set to "Bearer " + the value of the request property "$.sinkCredential.accessToken" And the request body complies with the OAS schema at "/components/schemas/PopulationDensityAsyncResponse" @@ -270,7 +270,7 @@ Feature: CAMARA Population Density Data API, vwip @population_density_data_400.06_invalid_url Scenario: Invalid sink - Given the request body property "$.sink" is not set to an url + Given the request body property "$.sink" is not set to a URL When the request "retrievePopulationDensity" is sent Then the response status code is 400 And the response header "x-correlator" has same value as the request header "x-correlator" diff --git a/documentation/API_documentation/Population-Density-Data_User_Story.md b/documentation/API_documentation/Population-Density-Data_User_Story.md index c88e267..859af4a 100644 --- a/documentation/API_documentation/Population-Density-Data_User_Story.md +++ b/documentation/API_documentation/Population-Density-Data_User_Story.md @@ -2,7 +2,7 @@ Items | Details | |---|---| -| **Summary** | The API provides estimation of Population Density for a specific area at a future period time, considering historical anonymized information of the network connected devices in the requested area.| +| **Summary** | The API provides estimation of Population Density for a specific area at a future period of time, considering historical anonymized information of the network connected devices in the requested area.| | **Actors and scope** | **Scope:** Retrieve predicted population density for a defined polygonal area and time interval; provide insights into population patterns to support strategic planning.

**Use Case 1 — Drone Route Planning:** Identify zones to avoid due to high population-related risk; determine optimal time window to fly between two points (A–B) minimizing population exposure.

**Use Case 2 — Urban Planning:** Data-driven optimization of public services/resource allocation; support simulation and impact assessment for urban mobility and infrastructure planning.| | **Pre-conditions** | The client must provide:
- **Requested Area (Required):** Polygonal area defined by coordinates forming a closed loop.
- **Start Time (Required):** Future controlled time of departure.
- **End Time (Required):** Future controlled time of arrival.
- **Precision (Optional):** Geohash precision level.
- **Sink (Optional):** Destination system/endpoint for delivery.
- **Sink Credentials (Optional):** AuthN/AuthZ details to access the sink.| | **Activities / Steps** | 1) The client submits a request including the inputs above.
2) The API responds **synchronously** (response body) or **asynchronously** (delivered to sink), including:
- **a) Cell Coordinates:** Geohash string representing the cell.
- **b) Population Density Metrics:** per cell in **1-hour intervals** with **min / avg / max** population.
- **c) Data Type (k-anonymity):** `Low_Density` (below threshold, cannot disclose) or `Density_Estimation` (values available and disclosed).| diff --git a/documentation/MeetingMinutes/MeetingMinutes07-02.md b/documentation/MeetingMinutes/MeetingMinutes07-02.md deleted file mode 100644 index 02f9537..0000000 --- a/documentation/MeetingMinutes/MeetingMinutes07-02.md +++ /dev/null @@ -1,99 +0,0 @@ -# CAMARA Population Density Data API - Follow-up meeting #1 - 2024-02-07 - -*February 07th, 2024* - -## Attendees - -|| -| --- | -|Sachin Kumar (Vodafone)| -|Thomas Neubauer (Dimetor)| -|Violeta Gonzalez Fernandez (Telefonica)| -|Jorge Garcia Hospital (Telefonica)| - - - -Population Density Data API minutes: [https://github.com/camaraproject/PopulationDensityData/tree/main/documentation/MeetingMinutes](https://github.com/camaraproject/PopulationDensityData/tree/main/documentation/MeetingMinutes) - -## Agenda - -* Approval of previous meeting minutes #1 and meeting agenda - * Confluence adoption -* Open issues and PRs - * Issues: #4 - * PRs: #3 #5 -* Timeline and next steps -* AoB - - -## Open Issues & PRs
- - -Item | Who | Description ----- | ---- | ---- -[PR#1](https://github.com/camaraproject/PopulationDensityData/pull/1) | Telefonica | Previous meeting material and minutes -[PR#2](https://github.com/camaraproject/PopulationDensityData/pull/2) | Telefonica | Readme update -[PR#3](https://github.com/camaraproject/PopulationDensityData/pull/3) | Verizon | Including new subgroup maintainer -[Issue#4](https://github.com/camaraproject/PopulationDensityData/issues/4) | Telefonica | Innitial scope agreement -[PR#5](https://github.com/camaraproject/PopulationDensityData/pull/5) | Telefonica | Innitial PopulationDensityData API spec proposal - -## Approval of previous meeting minutes & documentation (#1) - -[KO Meeting Minutes](https://github.com/camaraproject/PopulationDensityData/blob/main/documentation/MeetingMinutes/PopulationDensityDataAPI-KOmeeting_2024-01-24.md) - -### Readme modifications (#2) - -Including the description of the group, link to minutes and schedule of the following meetings (also meeting link) - -### Confluence - to be agreed - -CAMARA is moving the documentation (meeting minutes mainly) to the [wiki.camaraproject.org](https://wiki.camaraproject.org/) Confluence webpage. Proposal to be agreed on moving meeting minutes for following meetings in that format from now on. - -Agreement: To be used from next meeting, minutes and agenda will be placed there. - -### New Maintainer (#3) - -Verizon proposed as new maintainer of the API subgroup. - -### API proposal review (#5) - -Different discussions raised during the API review: -* **Information in water zones**: Operators and therefore API can only provide data of those zones where it is operating. Water zones are not considered and current implementation will provive an error in case the requested zone includes a water zone. Dimetor proposes to only provide "nonData" or null response for those specific cells, but not a complete error, concious of the multiple cases where flights will indeed consider wateer zones due to the expected low population density. - -* Open discussion on **default and limit values** for the API characteristics: - * **Minimum and maximum date** minimum and maximum date allowed as requested time range. Currently, 15 minutes is set as the minimum (soonest time target the request can consider), and 1 year for maximum (longer date with information to extrapolate). TBD - - * **Time interval** in the request: Maximum (and minimum) lenght of the time range requested in the API. TBD - - * **Time granularity** in the response: Lenght of the information pieces in which the time interval is subdivided in the response. Default value is proposed in 1hour, so the response will include density information of each 1hour range that can be included in the requested interval. E.g. If request interval is 15minutes to 1 hour, 1 only result will be provided, if 3 hours and 45 minutes are requested, 4 results will be provided (from 0-1, 1-2, 2-3, 3-3:45). TBD - * **Cell size/granularity** in the response: Currently both cell definition systems allow to implement different size of cells. TBD - -* Cell's format in the response: Currently, API support two different formats of defining the cells in which the requested area is divided for providing the information in the response: - * **Boundary Cells**: The cell is defined by a polygon, composed by the internal area bounded by 4 geo positions. *Same solution as in Location Retrieval API - - * **Geohash Cells**: The Coordinates of the cell are representad as a string using the [Geohash system](https://en.wikipedia.org/wiki/Geohash). The value length, and thus the cell granularity, is determined by the implementation. - - Discussion on which mechanisms to restrict, or how to allow developers to select one of them if multiple are supported.\ - - *(Note that optionality in one side implies obligatory for the other, in this case forcing developers to support both options)* - -## Discussion - -Item | Discussion ----- | ---- -[PR#1](https://github.com/camaraproject/PopulationDensityData/pull/1) | Approval of previous meetinge minutes → Approved -[PR#2](https://github.com/camaraproject/PopulationDensityData/pull/2) | Confirmation of subgroup readme information → Noted -[PR#3](https://github.com/camaraproject/PopulationDensityData/pull/3) | Confirm Verizon as new maintainer → Noted -[Issue#4](https://github.com/camaraproject/PopulationDensityData/issues/4) | Close scope of the innitial API → Approved -[PR#5](https://github.com/camaraproject/PopulationDensityData/pull/5) | Review proposal of innitial API code → [Issue#6](https://github.com/camaraproject/PopulationDensityData/issues/6) [Issue#7](https://github.com/camaraproject/PopulationDensityData/issues/7) [Issue#8](https://github.com/camaraproject/PopulationDensityData/issues/8) Oppened for offline Oppened for offline discussion. -AoB | - - -## Next steps -1. Review and close open points PDD → Follow-up meeting #2 -2. Propose innitial draft of algorithm → Follow-up meeting #2 -3. Draft API spec agreement → Follow-up meeting #3 - - -- Next call will be **February 21th, 2024** - -

\ No newline at end of file diff --git a/documentation/MeetingMinutes/PopulationDensityDataAPI-KOmeeting_2024-01-24.md b/documentation/MeetingMinutes/PopulationDensityDataAPI-KOmeeting_2024-01-24.md deleted file mode 100644 index 6f13d1e..0000000 --- a/documentation/MeetingMinutes/PopulationDensityDataAPI-KOmeeting_2024-01-24.md +++ /dev/null @@ -1,65 +0,0 @@ -# CAMARA Population Density Data API - KO meeting - 2024-01-24 - -*January 24th, 2024* - -## Attendees - -|| -| --- | -|Sachin Kumar (Vodafone)| -|Thomas Wana (Dimetor)| -|Thomas Neubauer (Dimetor)| -|Violeta Gonzalez Fernandez (Telefonica)| -|Jorge Garcia Hospital (Telefonica)| - - - -Population Density Data API minutes: [https://github.com/camaraproject/PopulationDensityData/tree/main/documentation/MeetingMinutes](https://github.com/camaraproject/PopulationDensityData/tree/main/documentation/MeetingMinutes) - -## Agenda - -* Presentation of the working group - * Density Population Data reference use cases -* Schedule and bi-weekly planification -* Timeline and next steps -* AoB - - -## Open Issues & PRs
- - -Item | Who | Description ----- | ---- | ---- -N/A | N/A | N/A - -## Introduction to the working group - -Supporting material: [KO supporting material](https://github.com/camaraproject/PopulationDensityData/tree/main/documentation/SupportingDocuments/KO%20-%20Population%20Density%20Data%20Proposal%20for%20Camara%20Standarizationv3.pptx) - -### Scope - -**API definition:** The Population Density Data API enables developers with the capability to get population density estimations for a specific area at a future date and time, considering historical anonymized information of the network connected devices in the requested area. - -**API inputs (TBC):** Geographical area (2D map) and time range (future) - -**API outputs (TBC):** Max, min and average estimated statistics of population density for the required map, divided in uniform cells depending on the accuracy of the data. In a time series, to include information for the complete requested time range - - -### Density Population Data reference use cases - -For the reference use case, the API fills the need of assessing the ground risk to allow safe drone flights by providing estimations of the number of people under a drone flight path. This assessment will be needed every time a drone flight in the specific category need to conduct an operation and will help the operator to identify operational limitations, to develop the appropriate operational procedures and to identify mitigations and safety objectives. More information in [KO supporting material](https://github.com/camaraproject/PopulationDensityData/tree/main/documentation/SupportingDocuments/KO%20-%20Population%20Density%20Data%20Proposal%20for%20Camara%20Standarizationv3.pptx) - -## Discussion - -Item | Discussion ----- | ---- -Group Scope | Telefonica shares the proposal to include not only the specification of the API but also the agreement on the required algorithms of prediction and interpolation that are required in the API to provide a homogeneous response among operators. Aggrement reached. -Meeting Schedule | It's agreed to keep KO time schedule to be replicated in the following repetitions of the subgroup meetings.
Be-weekly meeting on Wednesday, 14:00 Europe/Amsterdam (CET) (13:00 UTC, 12:00 UTC during European DST), starting February, 7th. -Timeline and next steps | Schedule to close scope, prepare innitial yaml proposal and close RC version is proposed. -AoB | N/A - - - -- Next call will be **February 7th, 2024** - -

diff --git a/documentation/MeetingMinutes/README.MD b/documentation/MeetingMinutes/README.MD deleted file mode 100644 index 37aa0ff..0000000 --- a/documentation/MeetingMinutes/README.MD +++ /dev/null @@ -1 +0,0 @@ -This README.MD can be deleted when the first file is added to this directory.