From 863485236ddf5bc404c47c0fdf405b048118330e Mon Sep 17 00:00:00 2001 From: Alberto Ramos Monagas Date: Mon, 18 May 2026 12:11:08 +0200 Subject: [PATCH 1/6] Add new changes for Sync26 (geohashlist) --- .../population-density-data.yaml | 76 ++++++++++++++++--- 1 file changed, 66 insertions(+), 10 deletions(-) diff --git a/code/API_definitions/population-density-data.yaml b/code/API_definitions/population-density-data.yaml index 8966b51..ef16a72 100644 --- a/code/API_definitions/population-density-data.yaml +++ b/code/API_definitions/population-density-data.yaml @@ -46,10 +46,16 @@ info: # API Functionality - Once a developer specifies (1) the area as a polygon shape, (2) a precision level and (3) time interval + Once a developer specifies (1) the area (either as a polygon shape or as a list of geohashes), + (2) a precision level (only when the area is a polygon) and (3) time interval in which they want to obtain the population density, the API returns a data set consisting of a sequence of time ranges, with each time range containing the - input polygon subdivided into equal-sized grid cells. + requested area subdivided into equal-sized grid cells. + + + When the area is provided as a list of geohashes (`areaType: GEOHASHLIST`), the response + contains one cell per requested geohash; each geohash determines the granularity of its own + response cell, and the `precision` request property MUST NOT be included. For each of the equal-sized cells of the grid, an estimated population density is @@ -74,6 +80,25 @@ info: supported area, an empty array is returned. + When the area is specified as a list of geohashes (`areaType: GEOHASHLIST`): + + - All MNOs must support the `POLYGON` area type; support for `GEOHASHLIST` is optional. + If the MNO does not support `GEOHASHLIST`, the API returns the error response + `POPULATION_DENSITY_DATA.UNSUPPORTED_AREA_TYPE`. + + - The requested geohashes do not need to be adjacent or contiguous; the API + returns one cell per requested geohash. + + - Geohashes within the same request may have different precisions (string lengths), + as long as the MNO supports all of them. If any geohash uses a precision not + supported by the MNO, the API returns the error response + `POPULATION_DENSITY_DATA.UNSUPPORTED_PRECISION`. + + - Geohashes within the list that fall outside the MNO coverage area are returned + with cell type `NO_DATA`. If the entire list is outside the coverage area, the + response will have `status` set to `AREA_NOT_SUPPORTED`. + + 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`) @@ -331,8 +356,10 @@ components: precision: type: integer description: >- - Precision required of response cells. Precision defines a geohash level and corresponds to the length of the geohash for each cell. More information at [Geohash system](https://en.wikipedia.org/wiki/Geohash)" - If not included the default precision level 7 is used by default. In case of using a not supported level by the MNO, the API returns the error response `POPULATION_DENSITY_DATA.UNSUPPORTED_PRECISION`. + Precision required of response cells. Precision defines a geohash level and corresponds to the length of the geohash for each cell. More information at [Geohash system](https://en.wikipedia.org/wiki/Geohash). + If not included the default precision level 7 is used by default. + Values within the schema range (1–12) that are not supported by the MNO return the error response `422 POPULATION_DENSITY_DATA.UNSUPPORTED_PRECISION`. Values outside the schema range are invalid per the OpenAPI definition and return `400 INVALID_ARGUMENT` via request validation. + This property MUST only be set when `area.areaType` is `POLYGON`. When `area.areaType` is `GEOHASHLIST`, each requested geohash determines the granularity of its own response cell; if `precision` is sent, the API returns a `400 INVALID_ARGUMENT` error. minimum: 1 maximum: 12 default: 7 @@ -362,13 +389,16 @@ components: propertyName: areaType mapping: POLYGON: "#/components/schemas/Polygon" + GEOHASHLIST: "#/components/schemas/GeohashList" AreaType: type: string description: | Type of this area. POLYGON - The area is defined as a polygon. + GEOHASHLIST - The area is defined as a list of geohashes. enum: - POLYGON + - GEOHASHLIST Polygon: description: Polygonal area. The Polygon should be a simple polygon, i.e. should not intersect itself. allOf: @@ -412,6 +442,30 @@ components: format: double minimum: -180 maximum: 180 + GeohashList: + description: >- + Area defined as a list of geohashes. Geohashes do not need to be adjacent or contiguous and may have different precision levels (string lengths), as long as the MNO supports all of them. The `precision` request property MUST NOT be set when `areaType` is `GEOHASHLIST`; if set, the API returns a `400 INVALID_ARGUMENT` error. + allOf: + - $ref: "#/components/schemas/Area" + - type: object + required: + - geohashes + properties: + geohashes: + type: array + description: List of geohashes that define the area of interest. + minItems: 1 + items: + $ref: "#/components/schemas/Geohash" + Geohash: + type: string + description: >- + Geohash string identifying a cell using the [Geohash system](https://en.wikipedia.org/wiki/Geohash), + encoding a geographic location into a short string. Characters are taken from the + base-32 geohash alphabet (`0-9` and `b-z` excluding `a`, `i`, `l`, `o`). + The length of the string determines the cell granularity (precision). + pattern: ^[0-9bcdefghjkmnpqrstuvwxyz]{1,12}$ + example: ezdmemd SinkCredential: type: object properties: @@ -615,12 +669,7 @@ components: case of a cell not supported `dataType` value is "NO_DATA" properties: geohash: - type: string - description: >- - Coordinates of the cell represented as a string using the [Geohash system](https://en.wikipedia.org/wiki/Geohash). - Encoding a geographic location into a short string. The value length, - and thus, the cell granularity, is determined by the request body property `precision`. - example: ezdmemd + $ref: '#/components/schemas/Geohash' dataType: type: string enum: @@ -901,6 +950,7 @@ components: - Indicated combination of area, time interval and precision is too big ("code": "POPULATION_DENSITY_DATA.UNSUPPORTED_REQUEST", "message": "Indicated combination of area, time interval and precision is too big") - Indicated cell precision (Geohash level) is not supported ("code": "POPULATION_DENSITY_DATA.UNSUPPORTED_PRECISION", "message": "Indicated cell precision (Geohash level) is not supported") - Indicated combination of area, time interval and precision is too big for a sync response ("code": "POPULATION_DENSITY_DATA.UNSUPPORTED_SYNC_RESPONSE", "message": "Indicated combination of area, time interval and precision is too big for a sync response") + - The requested `areaType` is not supported by the MNO ("code": "POPULATION_DENSITY_DATA.UNSUPPORTED_AREA_TYPE", "message": "The requested areaType is not supported by the MNO") headers: x-correlator: $ref: '#/components/headers/x-correlator' @@ -919,6 +969,7 @@ components: - POPULATION_DENSITY_DATA.UNSUPPORTED_REQUEST - POPULATION_DENSITY_DATA.UNSUPPORTED_PRECISION - POPULATION_DENSITY_DATA.UNSUPPORTED_SYNC_RESPONSE + - POPULATION_DENSITY_DATA.UNSUPPORTED_AREA_TYPE examples: POPULATION_DENSITY_DATA_422_UNSUPPORTED_REQUEST: value: @@ -938,6 +989,11 @@ components: message: >- Indicated combination of area, time interval and precision is too big for synchronous processing and asynchronous processing is not enabled + POPULATION_DENSITY_DATA_422_UNSUPPORTED_AREA_TYPE: + value: + status: 422 + code: POPULATION_DENSITY_DATA.UNSUPPORTED_AREA_TYPE + message: The requested areaType is not supported by the MNO Generic429: description: Too Many Requests headers: From 9b30eb38250273d03e4a669d60d82c02d3d14ce2 Mon Sep 17 00:00:00 2001 From: Alberto Ramos Monagas Date: Thu, 4 Jun 2026 12:38:45 +0200 Subject: [PATCH 2/6] Add commonalities 0.8.0 changes --- .../population-density-data.yaml | 117 +++++++++--------- 1 file changed, 60 insertions(+), 57 deletions(-) diff --git a/code/API_definitions/population-density-data.yaml b/code/API_definitions/population-density-data.yaml index ef16a72..8780eef 100644 --- a/code/API_definitions/population-density-data.yaml +++ b/code/API_definitions/population-density-data.yaml @@ -40,7 +40,7 @@ info: * **Notification URL and token**: Developers may provide a callback URL (`sink`) for receiving an async response. This is an optional parameter. 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` MUST be set to `ACCESSTOKEN` if provided. + property to protect the notification endpoint. In the current version,`sinkCredential.credentialType` MUST be set to `ACCESSTOKEN` or `PRIVATE_KEY_JWT` if provided. 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. @@ -106,7 +106,7 @@ info: 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` - MUST be set to `ACCESSTOKEN` if provided. + MUST be set to `ACCESSTOKEN` or `PRIVATE_KEY_JWT` if provided. For requests with a combination of `area`, `precision`, `startTime` and `endTime` @@ -160,7 +160,7 @@ info: url: https://www.apache.org/licenses/LICENSE-2.0.html version: wip - x-camara-commonalities: 0.6 + x-camara-commonalities: 0.8.0 externalDocs: description: Product documentation at CAMARA. url: https://github.com/camaraproject/PopulationDensityData @@ -326,7 +326,9 @@ components: schemas: XCorrelator: type: string + description: Correlator string, UUID format recommended but any string matching the pattern can be used pattern: ^[a-zA-Z0-9-_:;.\/<>{}]{0,256}$ + maxLength: 256 example: "b4333c46-49c0-4f62-80d7-f0ef930f1c46" PopulationDensityRequest: type: object @@ -340,6 +342,7 @@ components: startTime: type: string format: date-time + maxLength: 64 description: >- Start date time. It must follow [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) and must have time zone. Recommended format is yyyy-MM-dd'T'HH:mm:ss.SSSZ @@ -347,6 +350,7 @@ components: endTime: type: string format: date-time + maxLength: 64 description: >- End date time. It must follow [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) and must have time zone. Recommended format is yyyy-MM-dd'T'HH:mm:ss.SSSZ @@ -355,6 +359,7 @@ components: example: "2023-07-03T12:27:08.312Z" precision: type: integer + format: int32 description: >- Precision required of response cells. Precision defines a geohash level and corresponds to the length of the geohash for each cell. More information at [Geohash system](https://en.wikipedia.org/wiki/Geohash). If not included the default precision level 7 is used by default. @@ -366,6 +371,7 @@ components: sink: type: string format: uri + maxLength: 2048 description: The address where the API response will be asynchronously delivered, using the HTTP protocol. pattern: ^https:\/\/.+$ example: 'https://endpoint.example.com/sink' @@ -455,6 +461,7 @@ components: type: array description: List of geohashes that define the area of interest. minItems: 1 + maxItems: 1000 items: $ref: "#/components/schemas/Geohash" Geohash: @@ -465,108 +472,83 @@ components: base-32 geohash alphabet (`0-9` and `b-z` excluding `a`, `i`, `l`, `o`). The length of the string determines the cell granularity (precision). pattern: ^[0-9bcdefghjkmnpqrstuvwxyz]{1,12}$ + maxLength: 12 example: ezdmemd SinkCredential: + description: A sink credential provides authentication or authorization information necessary to enable delivery of events to a target. type: object properties: credentialType: type: string enum: - - PLAIN - ACCESSTOKEN - - REFRESHTOKEN + - PRIVATE_KEY_JWT description: | - The type of the credential. - Note: Type of the credential - MUST be set to ACCESSTOKEN for now + The type of the credential - MUST be set to ACCESSTOKEN or PRIVATE_KEY_JWT for now discriminator: propertyName: credentialType mapping: - PLAIN: '#/components/schemas/PlainCredential' ACCESSTOKEN: '#/components/schemas/AccessTokenCredential' - REFRESHTOKEN: '#/components/schemas/RefreshTokenCredential' + PRIVATE_KEY_JWT: '#/components/schemas/PrivateKeyJWTCredential' required: - credentialType - PlainCredential: - type: object - description: A plain credential as a combination of an identifier and a secret. - allOf: - - $ref: '#/components/schemas/SinkCredential' - - type: object - required: - - identifier - - secret - properties: - identifier: - description: The identifier might be an account or username. - type: string - secret: - description: The secret might be a password or passphrase. - type: string AccessTokenCredential: type: object - description: An access token credential. + description: An access token credential. This type of credential is meant to be used by API Consumers that have limited capabilities to handle authorization requests. allOf: - $ref: '#/components/schemas/SinkCredential' - type: object properties: accessToken: - description: REQUIRED. An access token is a previously acquired token granting access to the target resource. + description: REQUIRED. An access token is a token granting access to the target resource. type: string + maxLength: 4096 + writeOnly: true accessTokenExpiresUtc: type: string format: date-time + maxLength: 64 description: | REQUIRED. An absolute (UTC) timestamp at which the token shall be considered expired. If the access token is a JWT and registered "exp" (Expiration Time) claim is present, the two expiry times should match. It must follow [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) and must have time zone. - Recommended format is yyyy-MM-dd'T'HH:mm:ss.SSSZ (i.e. which allows 2023-07-03T14:27:08.312+02:00 or 2023-07-03T12:27:08.312Z) example: "2023-07-03T12:27:08.312Z" accessTokenType: - description: REQUIRED. Type of the access token (See [OAuth 2.0](https://tools.ietf.org/html/rfc6749#section-7.1)). For the current version of the API the type MUST be set to `Bearer`. + description: REQUIRED. Type of the access token (See [OAuth 2.0](https://tools.ietf.org/html/rfc6749#section-7.1)). type: string + writeOnly: true enum: - bearer required: - accessToken - accessTokenExpiresUtc - accessTokenType - RefreshTokenCredential: + PrivateKeyJWTCredential: type: object - description: An access token credential with a refresh token. + description: Use PRIVATE_KEY_JWT to get an access token. This type of credential is to be used by clients that have an authorization server. allOf: - $ref: '#/components/schemas/SinkCredential' - type: object properties: - accessToken: - description: REQUIRED. An access token is a previously acquired token granting access to the target resource. + clientId: + description: The client ID used to authenticate when requesting an access token using PRIVATE_KEY_JWT. type: string - accessTokenExpiresUtc: + maxLength: 128 + writeOnly: true + tokenUri: + description: The URI where to request an access token using PRIVATE_KEY_JWT. type: string - format: date-time - description: | - REQUIRED. An absolute (UTC) timestamp at which the token shall be considered expired. - If the access token is a JWT and registered "exp" (Expiration Time) claim is present, the two expiry times should match. - It must follow [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) and must have time zone. - Recommended format is yyyy-MM-dd'T'HH:mm:ss.SSSZ (i.e. which allows 2023-07-03T14:27:08.312+02:00 or 2023-07-03T12:27:08.312Z) - example: "2023-07-03T12:27:08.312Z" - accessTokenType: - description: REQUIRED. Type of the access token (See [OAuth 2.0](https://tools.ietf.org/html/rfc6749#section-7.1)). - type: string - enum: - - bearer - refreshToken: - description: REQUIRED. An refresh token credential used to acquire access tokens. - type: string - refreshTokenEndpoint: + format: uri + maxLength: 2048 + pattern: ^https:\/\/.+$ + writeOnly: true + jwksUri: + description: The URI used to request the public key to verify that the JWT assertion was signed by PRIVATE_KEY_JWT. type: string format: uri - description: REQUIRED. A URL at which the refresh token can be traded for an access token. - required: - - accessToken - - accessTokenExpiresUtc - - accessTokenType - - refreshToken - - refreshTokenEndpoint + maxLength: 2048 + pattern: ^https:\/\/.+$ + readOnly: true PopulationDensityResponse: type: object description: >- @@ -584,10 +566,12 @@ components: to 2024-01-03T12:00:00Z and interval from 2024-01-03T12:00:00Z to 2024-01-03T13:00:00Z). items: $ref: '#/components/schemas/TimedPopulationDensityData' + maxItems: 168 status: $ref: '#/components/schemas/ResponseStatus' statusInfo: type: string + maxLength: 512 description: Information about the status, mandatory when property `status` is `OPERATION_NOT_COMPLETED` for adding extra information about the error. example: Some error happened during the processing of the request required: @@ -611,6 +595,7 @@ components: - operationId OperationId: type: string + maxLength: 256 description: The unique identifier of the asynchronous operation that is returned when the operation is initiated. ResponseStatus: type: string @@ -633,6 +618,7 @@ components: startTime: type: string format: date-time + maxLength: 64 description: >- Interval start time. It must follow [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) and must have time zone. Recommended format is yyyy-MM-dd'T'HH:mm:ss.SSSZ @@ -641,6 +627,7 @@ components: endTime: type: string format: date-time + maxLength: 64 description: >- Interval end time. It must follow [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) and must have time zone. Recommended format is yyyy-MM-dd'T'HH:mm:ss.SSSZ @@ -659,6 +646,7 @@ components: items: $ref: '#/components/schemas/CellPopulationDensityData' minItems: 1 + maxItems: 10000 CellPopulationDensityData: type: object description: >- @@ -698,12 +686,21 @@ components: properties: maxPplDensity: type: integer + format: int32 + minimum: 0 + maximum: 2147483647 description: Maximum people/km2 estimated for the defined area. minPplDensity: type: integer + format: int32 + minimum: 0 + maximum: 2147483647 description: Minimum people/km2 estimated for the defined area. pplDensity: type: integer + format: int32 + minimum: 0 + maximum: 2147483647 description: people/km2 estimation for the defined area. required: - maxPplDensity @@ -711,6 +708,7 @@ components: - pplDensity ErrorInfo: type: object + description: A structured error response providing details about a failed request, including the HTTP status code, an error code, and a human-readable message required: - status - code @@ -718,12 +716,17 @@ components: properties: status: type: integer + format: int32 + minimum: 100 + maximum: 599 description: HTTP response status code code: type: string + maxLength: 96 description: A human-readable code to describe the error message: type: string + maxLength: 512 description: A human-readable description of what the event represents responses: RetrieveLocationBadRequest400: From fb84a2b4b277fca0c1aca63bab7b9ba5d9453881 Mon Sep 17 00:00:00 2001 From: Alberto Ramos Monagas Date: Thu, 4 Jun 2026 12:42:37 +0200 Subject: [PATCH 3/6] Add changes to checklist --- ...opulation-density-data-API-Readiness-Checklist.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/documentation/API_documentation/population-density-data-API-Readiness-Checklist.md b/documentation/API_documentation/population-density-data-API-Readiness-Checklist.md index 30fe9f9..926eec7 100644 --- a/documentation/API_documentation/population-density-data-API-Readiness-Checklist.md +++ b/documentation/API_documentation/population-density-data-API-Readiness-Checklist.md @@ -5,15 +5,15 @@ Checklist for population-density-data 0.3.0 in release r3.2 | Nr | API release assets | alpha | release-candidate | initial
public | stable
public | Status | Reference information | |----|----------------------------------------------|:-----:|:-----------------:|:-------:|:------:|:----:|------| | 1 | API definition | M | M | M | M | Y | [link](/code/API_definitions/population-density-data.yaml) | -| 2 | Design guidelines from Commonalities applied | O | M | M | M | Y | [r3.3](https://github.com/camaraproject/Commonalities/releases/tag/r3.2) | -| 3 | Guidelines from ICM applied | O | M | M | M | Y | [r3.3](https://github.com/camaraproject/IdentityAndConsentManagement/releases/tag/r3.2) | -| 4 | API versioning convention applied | M | M | M | M | Y | v0.3.0 | +| 2 | Design guidelines from Commonalities applied | O | M | M | M | Y | [r4.3](https://github.com/camaraproject/Commonalities/releases/tag/r4.3) | +| 3 | Guidelines from ICM applied | O | M | M | M | Y | [r4.2](https://github.com/camaraproject/IdentityAndConsentManagement/releases/tag/r4.2) | +| 4 | API versioning convention applied | M | M | M | M | Y | v1.0.0 | | 5 | API documentation | M | M | M | M | Y | Embed documentation into API spec - [link](/code/API_definitions/population-density-data.yaml) | -| 6 | User stories | O | O | O | M | N | TBC | +| 6 | User stories | O | O | O | M | N | [link](documentation/API_documentation/Population-Density-Data_User_Story.md) | | 7 | Basic API test cases & documentation | O | M | M | M | Y | [link](/code/Test_definitions/population-density-data.feature) | | 8 | Enhanced API test cases & documentation | O | O | O | M | Y | [link](/code/Test_definitions/population-density-data.feature) | | 9 | Test result statement | O | O | O | M | N | TBC | -| 10 | API release numbering convention applied | M | M | M | M | Y | r3.2 | +| 10 | API release numbering convention applied | M | M | M | M | Y | r3.3 | | 11 | Change log updated | M | M | M | M | Y | [link](/CHANGELOG.md) | | 12 | Previous public release was certified | O | O | O | M | N | No | -| 13 | API description (for marketing) | O | O | M | M | Y | [wiki link](https://lf-camaraproject.atlassian.net/wiki/spaces/CAM/pages/74448957/PopulationDensityData+API+description) | +| 13 | API description (for marketing) | O | O | M | M | Y | [wiki link](https://lf-camaraproject.atlassian.net/wiki/spaces/CAM/pages/808452114/Population+Density+Data+API+description+v2) | From fc3e79a66a5485e9937b23429bc1400e88bb75f8 Mon Sep 17 00:00:00 2001 From: Alberto Ramos Monagas Date: Thu, 4 Jun 2026 13:00:57 +0200 Subject: [PATCH 4/6] Apply suggestion from @albertoramosmonagas --- .../population-density-data-API-Readiness-Checklist.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/API_documentation/population-density-data-API-Readiness-Checklist.md b/documentation/API_documentation/population-density-data-API-Readiness-Checklist.md index 926eec7..c96fd6f 100644 --- a/documentation/API_documentation/population-density-data-API-Readiness-Checklist.md +++ b/documentation/API_documentation/population-density-data-API-Readiness-Checklist.md @@ -13,7 +13,7 @@ Checklist for population-density-data 0.3.0 in release r3.2 | 7 | Basic API test cases & documentation | O | M | M | M | Y | [link](/code/Test_definitions/population-density-data.feature) | | 8 | Enhanced API test cases & documentation | O | O | O | M | Y | [link](/code/Test_definitions/population-density-data.feature) | | 9 | Test result statement | O | O | O | M | N | TBC | -| 10 | API release numbering convention applied | M | M | M | M | Y | r3.3 | +| 10 | API release numbering convention applied | M | M | M | M | Y | r4.1 | | 11 | Change log updated | M | M | M | M | Y | [link](/CHANGELOG.md) | | 12 | Previous public release was certified | O | O | O | M | N | No | | 13 | API description (for marketing) | O | O | M | M | Y | [wiki link](https://lf-camaraproject.atlassian.net/wiki/spaces/CAM/pages/808452114/Population+Density+Data+API+description+v2) | From c29bc19dfa09870bbbb3e4a1f688485e409bf256 Mon Sep 17 00:00:00 2001 From: Alberto Ramos Monagas Date: Tue, 23 Jun 2026 12:53:13 +0200 Subject: [PATCH 5/6] population-density-data-API-Readiness-Checklist.md - file should be deleted for Sync26 - release automation takes care about all needed information --- ...on-density-data-API-Readiness-Checklist.md | 19 ------------------- 1 file changed, 19 deletions(-) delete mode 100644 documentation/API_documentation/population-density-data-API-Readiness-Checklist.md diff --git a/documentation/API_documentation/population-density-data-API-Readiness-Checklist.md b/documentation/API_documentation/population-density-data-API-Readiness-Checklist.md deleted file mode 100644 index c96fd6f..0000000 --- a/documentation/API_documentation/population-density-data-API-Readiness-Checklist.md +++ /dev/null @@ -1,19 +0,0 @@ -# API Readiness Checklist - -Checklist for population-density-data 0.3.0 in release r3.2 - -| Nr | API release assets | alpha | release-candidate | initial
public | stable
public | Status | Reference information | -|----|----------------------------------------------|:-----:|:-----------------:|:-------:|:------:|:----:|------| -| 1 | API definition | M | M | M | M | Y | [link](/code/API_definitions/population-density-data.yaml) | -| 2 | Design guidelines from Commonalities applied | O | M | M | M | Y | [r4.3](https://github.com/camaraproject/Commonalities/releases/tag/r4.3) | -| 3 | Guidelines from ICM applied | O | M | M | M | Y | [r4.2](https://github.com/camaraproject/IdentityAndConsentManagement/releases/tag/r4.2) | -| 4 | API versioning convention applied | M | M | M | M | Y | v1.0.0 | -| 5 | API documentation | M | M | M | M | Y | Embed documentation into API spec - [link](/code/API_definitions/population-density-data.yaml) | -| 6 | User stories | O | O | O | M | N | [link](documentation/API_documentation/Population-Density-Data_User_Story.md) | -| 7 | Basic API test cases & documentation | O | M | M | M | Y | [link](/code/Test_definitions/population-density-data.feature) | -| 8 | Enhanced API test cases & documentation | O | O | O | M | Y | [link](/code/Test_definitions/population-density-data.feature) | -| 9 | Test result statement | O | O | O | M | N | TBC | -| 10 | API release numbering convention applied | M | M | M | M | Y | r4.1 | -| 11 | Change log updated | M | M | M | M | Y | [link](/CHANGELOG.md) | -| 12 | Previous public release was certified | O | O | O | M | N | No | -| 13 | API description (for marketing) | O | O | M | M | Y | [wiki link](https://lf-camaraproject.atlassian.net/wiki/spaces/CAM/pages/808452114/Population+Density+Data+API+description+v2) | From 628676ef101b4085b15c33fda4a5353f0c5f5c91 Mon Sep 17 00:00:00 2001 From: Alberto Ramos Monagas Date: Tue, 23 Jun 2026 14:35:07 +0200 Subject: [PATCH 6/6] Add changes from commonalities --- .../population-density-data.yaml | 396 ++---------------- 1 file changed, 44 insertions(+), 352 deletions(-) diff --git a/code/API_definitions/population-density-data.yaml b/code/API_definitions/population-density-data.yaml index fbbee40..1eb4902 100644 --- a/code/API_definitions/population-density-data.yaml +++ b/code/API_definitions/population-density-data.yaml @@ -1,7 +1,7 @@ openapi: 3.0.3 info: title: Population Density Data - description: >- + description: | The Population Density Data API exposes population density estimations for a specified area for a specified time interval. @@ -132,6 +132,7 @@ info: The API provides one endpoint that accepts POST requests for retrieving population density information in the specified area. + # 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. @@ -139,28 +140,33 @@ info: The specific authorization flows to be used will be agreed upon during the onboarding process, happening between the API consumer and the API provider, taking into account the declared purpose for accessing the API, whilst also being subject to the prevailing legal framework dictated by local legislation. 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. + # 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`. + 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. As a specific rule, error `501 - NOT_IMPLEMENTED` can be only a possible error response if it is explicitly documented in the API. + - # Further info and support + + # Request body strictness - (FAQs will be added in a later version of the documentation) + 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. + license: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0.html version: wip - x-camara-commonalities: 0.8.0 + x-camara-commonalities: wip externalDocs: description: Product documentation at CAMARA. url: https://github.com/camaraproject/PopulationDensityData @@ -188,7 +194,7 @@ paths: polygon area. operationId: retrievePopulationDensity parameters: - - $ref: '#/components/parameters/x-correlator' + - $ref: "../common/CAMARA_common.yaml#/components/parameters/x-correlator" requestBody: content: application/json: @@ -224,7 +230,7 @@ paths: The Population Density Data server will call this endpoint when the request result is ready. operationId: postNotification parameters: - - $ref: '#/components/parameters/x-correlator' + - $ref: "../common/CAMARA_common.yaml#/components/parameters/x-correlator" requestBody: description: Population density data result. content: @@ -245,17 +251,17 @@ paths: description: Successful notification headers: x-correlator: - $ref: '#/components/headers/x-correlator' + $ref: "../common/CAMARA_common.yaml#/components/headers/x-correlator" '400': - $ref: '#/components/responses/Generic400' + $ref: '../common/CAMARA_common.yaml#/components/responses/Generic400' '401': - $ref: '#/components/responses/Generic401' + $ref: '../common/CAMARA_common.yaml#/components/responses/Generic401' '403': - $ref: '#/components/responses/Generic403' + $ref: '../common/CAMARA_common.yaml#/components/responses/Generic403' '410': - $ref: '#/components/responses/Generic410' + $ref: '../common/CAMARA_common.yaml#/components/responses/Generic410' '429': - $ref: '#/components/responses/Generic429' + $ref: '../common/CAMARA_common.yaml#/components/responses/Generic429' security: - {} - notificationsBearerAuth: [] @@ -264,7 +270,7 @@ paths: description: Population density data result. headers: x-correlator: - $ref: '#/components/headers/x-correlator' + $ref: "../common/CAMARA_common.yaml#/components/headers/x-correlator" content: application/json: schema: @@ -281,7 +287,7 @@ paths: description: Population density data requested. This response is returned when the behaviour of the API is asynchronous. headers: x-correlator: - $ref: '#/components/headers/x-correlator' + $ref: "../common/CAMARA_common.yaml#/components/headers/x-correlator" content: application/json: schema: @@ -289,47 +295,25 @@ paths: '400': $ref: '#/components/responses/RetrieveLocationBadRequest400' '401': - $ref: '#/components/responses/Generic401' + $ref: '../common/CAMARA_common.yaml#/components/responses/Generic401' '403': - $ref: '#/components/responses/Generic403' + $ref: '../common/CAMARA_common.yaml#/components/responses/Generic403' '404': - $ref: '#/components/responses/Generic404' + $ref: '../common/CAMARA_common.yaml#/components/responses/Generic404' '422': $ref: '#/components/responses/RetrieveLocationUnprocessableContent422' '429': - $ref: '#/components/responses/Generic429' + $ref: '../common/CAMARA_common.yaml#/components/responses/Generic429' security: - openId: - population-density-data:read components: securitySchemes: openId: - type: openIdConnect - openIdConnectUrl: https://example.com/.well-known/openid-configuration + $ref: "../common/CAMARA_common.yaml#/components/securitySchemes/openId" notificationsBearerAuth: - description: Bearer authentication for notifications - type: http - scheme: bearer - bearerFormat: '{$request.body#sinkCredential.credentialType}' - headers: - x-correlator: - description: Correlation id for the different services. - schema: - $ref: "#/components/schemas/XCorrelator" - parameters: - x-correlator: - name: x-correlator - in: header - description: Correlation id for the different services. - schema: - $ref: "#/components/schemas/XCorrelator" + $ref: "../common/CAMARA_event_common.yaml#/components/securitySchemes/notificationsBearerAuth" schemas: - XCorrelator: - type: string - description: Correlator string, UUID format recommended but any string matching the pattern can be used - pattern: ^[a-zA-Z0-9-_:;.\/<>{}]{0,256}$ - maxLength: 256 - example: "b4333c46-49c0-4f62-80d7-f0ef930f1c46" PopulationDensityRequest: type: object description: >- @@ -340,21 +324,9 @@ components: area: $ref: '#/components/schemas/Area' startTime: - type: string - format: date-time - maxLength: 64 - description: >- - Start date time. It must follow [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) - and must have time zone. - example: "2023-07-03T12:27:08.312Z" + $ref: "../common/CAMARA_common.yaml#/components/schemas/DateTime" endTime: - type: string - format: date-time - maxLength: 64 - description: >- - End date time. It must follow [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) - and must have time zone. - example: "2023-07-03T12:27:08.312Z" + $ref: "../common/CAMARA_common.yaml#/components/schemas/DateTime" precision: type: integer format: int32 @@ -374,9 +346,7 @@ components: pattern: ^https:\/\/.+$ example: 'https://endpoint.example.com/sink' sinkCredential: - description: A sink credential provides authentication or authorization information necessary to enable delivery of events to a target. - allOf: - - $ref: '#/components/schemas/SinkCredential' + $ref: "../common/CAMARA_event_common.yaml#/components/schemas/SinkCredential" required: - area - startTime @@ -412,40 +382,7 @@ components: - boundary properties: boundary: - $ref: "#/components/schemas/PointList" - PointList: - description: List of points defining a polygon - type: array - items: - $ref: "#/components/schemas/Point" - minItems: 3 - maxItems: 15 - Point: - type: object - description: Coordinates (latitude, longitude) defining a location in a map - required: - - latitude - - longitude - properties: - latitude: - $ref: "#/components/schemas/Latitude" - longitude: - $ref: "#/components/schemas/Longitude" - example: - latitude: 50.735851 - longitude: 7.10066 - Latitude: - description: Latitude component of a location - type: number - format: double - minimum: -90 - maximum: 90 - Longitude: - description: Longitude component of location - type: number - format: double - minimum: -180 - maximum: 180 + $ref: "../common/CAMARA_common.yaml#/components/schemas/PointList" GeohashList: description: >- Area defined as a list of geohashes. Geohashes do not need to be adjacent or contiguous and may have different precision levels (string lengths), as long as the MNO supports all of them. The `precision` request property MUST NOT be set when `areaType` is `GEOHASHLIST`; if set, the API returns a `400 INVALID_ARGUMENT` error. @@ -472,81 +409,6 @@ components: pattern: ^[0-9bcdefghjkmnpqrstuvwxyz]{1,12}$ maxLength: 12 example: ezdmemd - SinkCredential: - description: A sink credential provides authentication or authorization information necessary to enable delivery of events to a target. - type: object - properties: - credentialType: - type: string - enum: - - ACCESSTOKEN - - PRIVATE_KEY_JWT - description: | - The type of the credential - MUST be set to ACCESSTOKEN or PRIVATE_KEY_JWT for now - discriminator: - propertyName: credentialType - mapping: - ACCESSTOKEN: '#/components/schemas/AccessTokenCredential' - PRIVATE_KEY_JWT: '#/components/schemas/PrivateKeyJWTCredential' - required: - - credentialType - AccessTokenCredential: - type: object - description: An access token credential. This type of credential is meant to be used by API Consumers that have limited capabilities to handle authorization requests. - allOf: - - $ref: '#/components/schemas/SinkCredential' - - type: object - properties: - accessToken: - description: REQUIRED. An access token is a token granting access to the target resource. - type: string - maxLength: 4096 - writeOnly: true - accessTokenExpiresUtc: - type: string - format: date-time - maxLength: 64 - description: | - REQUIRED. An absolute (UTC) timestamp at which the token shall be considered expired. - If the access token is a JWT and registered "exp" (Expiration Time) claim is present, the two expiry times should match. - It must follow [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) and must have time zone. - example: "2023-07-03T12:27:08.312Z" - accessTokenType: - description: REQUIRED. Type of the access token (See [OAuth 2.0](https://tools.ietf.org/html/rfc6749#section-7.1)). - type: string - writeOnly: true - enum: - - bearer - required: - - accessToken - - accessTokenExpiresUtc - - accessTokenType - PrivateKeyJWTCredential: - type: object - description: Use PRIVATE_KEY_JWT to get an access token. This type of credential is to be used by clients that have an authorization server. - allOf: - - $ref: '#/components/schemas/SinkCredential' - - type: object - properties: - clientId: - description: The client ID used to authenticate when requesting an access token using PRIVATE_KEY_JWT. - type: string - maxLength: 128 - writeOnly: true - tokenUri: - description: The URI where to request an access token using PRIVATE_KEY_JWT. - type: string - format: uri - maxLength: 2048 - pattern: ^https:\/\/.+$ - writeOnly: true - jwksUri: - description: The URI used to request the public key to verify that the JWT assertion was signed by PRIVATE_KEY_JWT. - type: string - format: uri - maxLength: 2048 - pattern: ^https:\/\/.+$ - readOnly: true PopulationDensityResponse: type: object description: >- @@ -577,12 +439,14 @@ components: - status AcceptedAsyncResponse: type: object + description: Accepted asynchronous response properties: operationId: $ref: '#/components/schemas/OperationId' required: - operationId PopulationDensityAsyncResponse: + description: Asynchronous population density data response allOf: - $ref: '#/components/schemas/PopulationDensityResponse' - type: object @@ -702,28 +566,6 @@ components: - maxPplDensity - minPplDensity - pplDensity - ErrorInfo: - type: object - description: A structured error response providing details about a failed request, including the HTTP status code, an error code, and a human-readable message - required: - - status - - code - - message - properties: - status: - type: integer - format: int32 - minimum: 100 - maximum: 599 - description: HTTP response status code - code: - type: string - maxLength: 96 - description: A human-readable code to describe the error - message: - type: string - maxLength: 512 - description: A human-readable description of what the event represents responses: RetrieveLocationBadRequest400: description: >- @@ -737,12 +579,12 @@ components: - 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)") headers: x-correlator: - $ref: '#/components/headers/x-correlator' + $ref: '../common/CAMARA_common.yaml#/components/headers/x-correlator' content: application/json: schema: allOf: - - $ref: "#/components/schemas/ErrorInfo" + - $ref: "../common/CAMARA_common.yaml#/components/schemas/ErrorInfo" - type: object properties: status: @@ -818,131 +660,6 @@ components: message: >- Indicated time period is partially in the past and partially in the future - Generic400: - description: Problem with the client request - headers: - x-correlator: - $ref: '#/components/headers/x-correlator' - content: - application/json: - schema: - allOf: - - $ref: "#/components/schemas/ErrorInfo" - - type: object - properties: - status: - enum: - - 400 - code: - enum: - - INVALID_ARGUMENT - examples: - GENERIC_400_INVALID_ARGUMENT: - description: Invalid Argument. Generic Syntax Exception - value: - status: 400 - code: INVALID_ARGUMENT - message: Client specified an invalid argument, request body or query param. - Generic401: - description: Unauthorized - headers: - x-correlator: - $ref: '#/components/headers/x-correlator' - content: - application/json: - schema: - allOf: - - $ref: "#/components/schemas/ErrorInfo" - - type: object - properties: - status: - enum: - - 401 - code: - enum: - - UNAUTHENTICATED - examples: - GENERIC_401_UNAUTHENTICATED: - description: Request cannot be authenticated - value: - status: 401 - code: UNAUTHENTICATED - message: Request not authenticated due to missing, invalid, or expired credentials. - Generic403: - description: Forbidden - headers: - x-correlator: - $ref: '#/components/headers/x-correlator' - content: - application/json: - schema: - allOf: - - $ref: "#/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. - Generic404: - description: Not found - headers: - x-correlator: - $ref: '#/components/headers/x-correlator' - content: - application/json: - schema: - allOf: - - $ref: "#/components/schemas/ErrorInfo" - - type: object - properties: - status: - enum: - - 404 - code: - enum: - - NOT_FOUND - examples: - GENERIC_404_NOT_FOUND: - description: Resource is not found - value: - status: 404 - code: NOT_FOUND - message: The specified resource is not found. - Generic410: - description: Gone - headers: - x-correlator: - $ref: "#/components/headers/x-correlator" - content: - application/json: - schema: - allOf: - - $ref: "#/components/schemas/ErrorInfo" - - type: object - properties: - status: - enum: - - 410 - code: - enum: - - GONE - examples: - GENERIC_410_GONE: - description: Use in notifications flow to allow API Consumer to indicate that its callback is no longer available - value: - status: 410 - code: GONE - message: Access to the target resource is no longer available. RetrieveLocationUnprocessableContent422: description: >- Problem with the client request. The following scenarios may exist: @@ -952,12 +669,12 @@ components: - The requested `areaType` is not supported by the MNO ("code": "POPULATION_DENSITY_DATA.UNSUPPORTED_AREA_TYPE", "message": "The requested areaType is not supported by the MNO") headers: x-correlator: - $ref: '#/components/headers/x-correlator' + $ref: '../common/CAMARA_common.yaml#/components/headers/x-correlator' content: application/json: schema: allOf: - - $ref: "#/components/schemas/ErrorInfo" + - $ref: "../common/CAMARA_common.yaml#/components/schemas/ErrorInfo" - type: object properties: status: @@ -993,40 +710,9 @@ components: status: 422 code: POPULATION_DENSITY_DATA.UNSUPPORTED_AREA_TYPE message: The requested areaType is not supported by the MNO - Generic429: - description: Too Many Requests - headers: - x-correlator: - $ref: "#/components/headers/x-correlator" - content: - application/json: - schema: - allOf: - - $ref: "#/components/schemas/ErrorInfo" - - type: object - properties: - status: - enum: - - 429 - code: - enum: - - QUOTA_EXCEEDED - - TOO_MANY_REQUESTS - examples: - GENERIC_429_QUOTA_EXCEEDED: - description: Request is rejected due to exceeding a business quota limit - value: - status: 429 - code: QUOTA_EXCEEDED - message: Out of resource quota. - GENERIC_429_TOO_MANY_REQUESTS: - description: Access to the API has been temporarily blocked due to rate or spike arrest limits being reached - value: - status: 429 - code: TOO_MANY_REQUESTS - message: Rate limit reached. examples: PopulationDensitySupportedAreaResponseExample: + description: Population density supported area response example value: status: SUPPORTED_AREA timedPopulationDensityData: @@ -1064,6 +750,7 @@ components: minPplDensity: 40 pplDensity: 100 PopulationDensityPartOfAreaNotSupportedResponseExample: + description: Population density part of area not supported response example value: status: PART_OF_AREA_NOT_SUPPORTED timedPopulationDensityData: @@ -1098,10 +785,12 @@ components: - geohash: ezdqemu dataType: NO_DATA PopulationDensityAreaNotSupportedResponseExample: + description: Population density area not supported response example value: status: AREA_NOT_SUPPORTED timedPopulationDensityData: [] PopulationDensitySupportedAreaAsyncResponseExample: + description: Population density supported area async response example value: status: SUPPORTED_AREA timedPopulationDensityData: @@ -1140,6 +829,7 @@ components: pplDensity: 100 operationId: 2322f362-eaab-4cf3-86d2-efcbdf3a7cb4 PopulationDensityPartOfAreaNotSupportedAsyncResponseExample: + description: Population density part of area not supported async response example value: status: PART_OF_AREA_NOT_SUPPORTED timedPopulationDensityData: @@ -1175,11 +865,13 @@ components: dataType: NO_DATA operationId: 2322f362-eaab-4cf3-86d2-efcbdf3a7cb4 PopulationDensityAreaNotSupportedAsyncResponseExample: + description: Population density area not supported async response example value: status: AREA_NOT_SUPPORTED timedPopulationDensityData: [] operationId: 2322f362-eaab-4cf3-86d2-efcbdf3a7cb4 PopulationDensityOperationNotCompletedExample: + description: Population density operation not completed example value: status: OPERATION_NOT_COMPLETED timedPopulationDensityData: []