diff --git a/code/API_definitions/population-density-data.yaml b/code/API_definitions/population-density-data.yaml index 9c7d94d..2b9bd58 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. @@ -40,16 +40,22 @@ 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. # 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`) @@ -81,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` @@ -107,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. @@ -114,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.6 + x-camara-commonalities: wip externalDocs: description: Product documentation at CAMARA. url: https://github.com/camaraproject/PopulationDensityData @@ -163,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: @@ -199,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: @@ -220,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: [] @@ -239,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: @@ -256,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: @@ -264,86 +295,59 @@ 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 - pattern: ^[a-zA-Z0-9-_:;.\/<>{}]{0,256}$ - example: "b4333c46-49c0-4f62-80d7-f0ef930f1c46" PopulationDensityRequest: type: object description: >- Request object for retrieving population density data in a specified area. **NOTE**: The difference between `startTime` and `endTime` cannot be greater than 7 days. + additionalProperties: false properties: area: $ref: '#/components/schemas/Area' startTime: - type: string - format: date-time - 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 - 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 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`, if not included the default precision level 7 is used. 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 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' 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 @@ -360,13 +364,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: @@ -376,139 +383,33 @@ 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 - SinkCredential: - type: object - properties: - credentialType: - type: string - enum: - - PLAIN - - ACCESSTOKEN - - REFRESHTOKEN - description: | - The type of the credential. - Note: Type of the credential - MUST be set to ACCESSTOKEN for now - discriminator: - propertyName: credentialType - mapping: - PLAIN: '#/components/schemas/PlainCredential' - ACCESSTOKEN: '#/components/schemas/AccessTokenCredential' - REFRESHTOKEN: '#/components/schemas/RefreshTokenCredential' - required: - - credentialType - PlainCredential: - type: object - description: A plain credential as a combination of an identifier and a secret. + $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. allOf: - - $ref: '#/components/schemas/SinkCredential' + - $ref: "#/components/schemas/Area" - type: object required: - - identifier - - secret + - geohashes 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. - 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. - type: string - accessTokenExpiresUtc: - 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. - 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`. - type: string - enum: - - bearer - required: - - accessToken - - accessTokenExpiresUtc - - accessTokenType - RefreshTokenCredential: - type: object - description: An access token credential with a refresh token. - 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. - type: string - accessTokenExpiresUtc: - 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. - 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: - 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 + geohashes: + type: array + description: List of geohashes that define the area of interest. + minItems: 1 + maxItems: 1000 + 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}$ + maxLength: 12 + example: ezdmemd PopulationDensityResponse: type: object description: >- @@ -526,10 +427,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: @@ -537,12 +440,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 @@ -553,6 +458,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 @@ -575,6 +481,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. @@ -582,6 +489,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. @@ -599,6 +507,7 @@ components: items: $ref: '#/components/schemas/CellPopulationDensityData' minItems: 1 + maxItems: 10000 CellPopulationDensityData: type: object description: >- @@ -609,12 +518,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: @@ -643,33 +547,26 @@ 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 - minPplDensity - pplDensity - ErrorInfo: - type: object - required: - - status - - code - - message - properties: - status: - type: integer - description: HTTP response status code - code: - type: string - description: A human-readable code to describe the error - message: - type: string - description: A human-readable description of what the event represents responses: RetrieveLocationBadRequest400: description: >- @@ -683,12 +580,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: @@ -764,145 +661,21 @@ 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: - 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' + $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: @@ -913,6 +686,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: @@ -932,40 +706,14 @@ components: message: >- Indicated combination of area, time interval and precision is too big for synchronous processing and asynchronous processing is not enabled - 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 + POPULATION_DENSITY_DATA_422_UNSUPPORTED_AREA_TYPE: 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. + status: 422 + code: POPULATION_DENSITY_DATA.UNSUPPORTED_AREA_TYPE + message: The requested areaType is not supported by the MNO examples: PopulationDensitySupportedAreaResponseExample: + description: Population density supported area response example value: status: SUPPORTED_AREA timedPopulationDensityData: @@ -1003,6 +751,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: @@ -1037,10 +786,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: @@ -1079,6 +830,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: @@ -1114,11 +866,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: [] 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 30fe9f9..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 | [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 | -| 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 | -| 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 | -| 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) |