From e4cb3d7f3a211418ec6bf314a631db0d3da109c0 Mon Sep 17 00:00:00 2001 From: maheshc01 Date: Mon, 20 Jul 2026 13:10:20 -0500 Subject: [PATCH 1/2] fix: align API with CAMARA Commonalities r4.3 validation requirements - Add 3 mandatory CAMARA info.description template blocks (authorization-and-authentication, additional-error-responses, request-body-strictness) - Set x-camara-commonalities: wip - Replace inline XCorrelator, ErrorInfo schemas with CAMARA_common.yaml refs - Replace Generic400/401/403/404/429 inline responses with CAMARA_common.yaml refs - Replace inline openId securityScheme, x-correlator header/parameter with CAMARA_common.yaml refs - Replace inline SingleIpv4Addr with CAMARA_common.yaml SingleIpv4Address ref - Add maxLength to all string fields (S-312) - Add maxItems: 20 to all array fields (S-309) - Add format: int32 and min: 1 to Port schema (S-310/S-311) - Delete placeholder README.MD (P-013) - Delete API-Readiness-Checklist.md (P-032) --- code/API_definitions/README.MD | 1 - .../application-endpoint-registration.yaml | 333 ++++-------------- ...nt-Registration-API-Readiness-Checklist.md | 19 - 3 files changed, 64 insertions(+), 289 deletions(-) delete mode 100644 code/API_definitions/README.MD delete mode 100644 documentation/API_documentation/Application-Endpoint-Registration-API-Readiness-Checklist.md diff --git a/code/API_definitions/README.MD b/code/API_definitions/README.MD deleted file mode 100644 index e9cd5a5..0000000 --- a/code/API_definitions/README.MD +++ /dev/null @@ -1 +0,0 @@ -Here you can add your definition file(s). Delete this README.MD file after the first file is added. diff --git a/code/API_definitions/application-endpoint-registration.yaml b/code/API_definitions/application-endpoint-registration.yaml index 7b2598c..42e6e2b 100644 --- a/code/API_definitions/application-endpoint-registration.yaml +++ b/code/API_definitions/application-endpoint-registration.yaml @@ -3,7 +3,7 @@ openapi: 3.0.3 info: title: Application Endpoints Registration version: wip - x-camara-commonalities: 0.6 + x-camara-commonalities: wip description: | The Application Endpoints Registration API provides a programmable interface for developers to register the endpoints of an application @@ -54,51 +54,32 @@ info: information. - DELETE deregisterApplicationEndpoint: Deregister an application's Endpoints. - ## Errors - - If the API call contains a formatting or any other syntactic error, - a `400 INVALID_ARGUMENT` error is returned. - - If the API call cannot be authenticated due to missing, invalid, or - expired credentials, a `401 UNAUTHENTICATED` error is returned. - - If the API call has a valid access token that does not have the - required scope, then a `403 PERMISSION_DENIED` error is returned. - - If the API call has an `applicationEndpointListId` that does not identify - any registered endpoint on the Edge Cloud, a `404 NOT_FOUND` error - is returned. + + # Additional CAMARA error responses - ### 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. - 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. + As a specific rule, error `501 - NOT_IMPLEMENTED` can be only a possible error response if it is explicitly documented in the API. + + # 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. + 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. + + 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. + - 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. + + # Request body strictness - 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. + 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. + # Further info and support @@ -123,9 +104,7 @@ servers: variables: apiRoot: default: http://localhost:9091 - description: | - API root, defined by service provider, e.g. - `api.example.com` or `api.example.com/somepath` + description: API root, defined by the service provider, e.g. `api.example.com` or `api.example.com/somepath` tags: - name: Application Endpoint Registration @@ -167,17 +146,17 @@ paths: schema: $ref: "#/components/schemas/ApplicationEndpointListId" "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" "404": - $ref: "#/components/responses/Generic404" + $ref: "../common/CAMARA_common.yaml#/components/responses/Generic404" "422": $ref: "#/components/responses/Generic422" "429": - $ref: "#/components/responses/Generic429" + $ref: "../common/CAMARA_common.yaml#/components/responses/Generic429" get: security: - openId: @@ -201,20 +180,21 @@ paths: application/json: schema: type: array + maxItems: 20 items: $ref: "#/components/schemas/ApplicationEndpointList" "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" "404": - $ref: "#/components/responses/Generic404" + $ref: "../common/CAMARA_common.yaml#/components/responses/Generic404" "422": $ref: "#/components/responses/Generic422" "429": - $ref: "#/components/responses/Generic429" + $ref: "../common/CAMARA_common.yaml#/components/responses/Generic429" "/application-endpoint-lists/{applicationEndpointListId}": parameters: @@ -249,17 +229,17 @@ paths: schema: $ref: "#/components/schemas/ApplicationEndpointList" "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" "404": - $ref: "#/components/responses/Generic404" + $ref: "../common/CAMARA_common.yaml#/components/responses/Generic404" "422": $ref: "#/components/responses/Generic422" "429": - $ref: "#/components/responses/Generic429" + $ref: "../common/CAMARA_common.yaml#/components/responses/Generic429" put: security: @@ -285,17 +265,17 @@ paths: x-correlator: $ref: '#/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" "404": - $ref: "#/components/responses/Generic404" + $ref: "../common/CAMARA_common.yaml#/components/responses/Generic404" "422": $ref: "#/components/responses/Generic422" "429": - $ref: "#/components/responses/Generic429" + $ref: "../common/CAMARA_common.yaml#/components/responses/Generic429" delete: security: @@ -315,42 +295,29 @@ paths: x-correlator: $ref: '#/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" "404": - $ref: "#/components/responses/Generic404" + $ref: "../common/CAMARA_common.yaml#/components/responses/Generic404" "422": $ref: "#/components/responses/Generic422" "429": - $ref: "#/components/responses/Generic429" + $ref: "../common/CAMARA_common.yaml#/components/responses/Generic429" components: securitySchemes: openId: - type: openIdConnect - description: Common security scheme for all CAMARA APIs - openIdConnectUrl: https://example.com/.well-known/openid-configuration + $ref: "../common/CAMARA_common.yaml#/components/securitySchemes/openId" headers: x-correlator: - description: Correlation id for the different services - schema: - $ref: "#/components/schemas/XCorrelator" + $ref: "../common/CAMARA_common.yaml#/components/headers/x-correlator" parameters: x-correlator: - name: x-correlator - in: header - description: Correlation id for the different services - schema: - $ref: "#/components/schemas/XCorrelator" + $ref: "../common/CAMARA_common.yaml#/components/parameters/x-correlator" schemas: - XCorrelator: - type: string - pattern: ^[a-zA-Z0-9-_:;.\/<>{}]{0,256}$ - example: "b4333c46-49c0-4f62-80d7-f0ef930f1c46" - ApplicationEndpointsInfo: description: Endpoint information of the Application deployed across different Edge Cloud Zones. @@ -358,16 +325,19 @@ components: properties: applicationEndpoints: type: array + maxItems: 20 description: List of endpoints of the application deployed across various Edge Cloud Zones items: $ref: "#/components/schemas/ApplicationEndpoint" applicationProviderName: type: string + maxLength: 256 description: Name of the Application Provider example: "AppProvider" applicationDescription: type: string + maxLength: 2048 description: Description of the application. example: "This is a V2X application." applicationProfileId: @@ -421,7 +391,7 @@ components: domainName: $ref: "#/components/schemas/DomainName" ipv4Address: - $ref: "#/components/schemas/SingleIpv4Addr" + $ref: "../common/CAMARA_common.yaml#/components/schemas/SingleIpv4Address" ipv6Address: $ref: "#/components/schemas/SingleIpv6Addr" port: @@ -430,6 +400,7 @@ components: $ref: "#/components/schemas/EdgeCloudZone" applicationEndpointDescription: type: string + maxLength: 2048 description: Description of the application endpoint example: "V2X app deployed at ZoneA" @@ -461,6 +432,7 @@ components: description: A unique identifier for the Edge Cloud Zone. type: string format: uuid + maxLength: 36 example: "123e4567-e89b-12d3-a456-426614174000" EdgeCloudRegion: @@ -468,6 +440,7 @@ components: The EdgeCloudProvider's name for the region where the Edge Cloud Zone is located. type: string + maxLength: 64 pattern: ^[A-Za-z0-9]([A-Za-z0-9-]{0,53}[A-Za-z0-9])?$ example: "us-west-1" @@ -483,12 +456,14 @@ components: EdgeCloudProvider: description: The provider of the Edge Cloud. type: string + maxLength: 64 pattern: ^[A-Za-z0-9]([A-Za-z0-9-]{0,53}[A-Za-z0-9])?$ example: "ProviderA" EdgeCloudZoneName: description: The name of the Edge Cloud Zone. type: string + maxLength: 64 pattern: ^[A-Za-z0-9]([A-Za-z0-9-]{0,53}[A-Za-z0-9])?$ example: "ZoneA" @@ -500,6 +475,7 @@ components: used to reference the registered endpoints in subsequent operations. type: string format: uuid + maxLength: 36 readOnly: true additionalProperties: false example: "98765432-e89b-12d3-a456-426614174999" @@ -510,6 +486,7 @@ components: the application's network and compute characteristics. type: string format: uuid + maxLength: 36 example: "123e4567-e89b-12d3-a456-426614174000" DomainName: @@ -521,172 +498,25 @@ components: minLength: 4 example: "app.example.com" - SingleIpv4Addr: - description: A single IPv4 address with no subnet mask - type: string - format: ipv4 - example: "84.125.93.10" - SingleIpv6Addr: description: | Single IPv6 address with no subnet mask type: string format: ipv6 + maxLength: 45 example: 2001:db8:85a3:8d3:1319:8a2e:370:7344 Port: description: | TCP or UDP port number for the application endpoint. - Valid range is 0-65535. + Valid range is 1-65535. type: integer - minimum: 0 + format: int32 + minimum: 1 maximum: 65535 example: 8080 - ErrorInfo: - description: Common schema for errors - type: object - required: - - status - - code - - message - properties: - status: - type: integer - description: HTTP status code returned along with this error response - code: - type: string - description: Code given to this error - message: - type: string - description: Detailed error description responses: - Generic400: - description: Bad 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 - - OUT_OF_RANGE - 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. - GENERIC_400_OUT_OF_RANGE: - description: Out of Range. Specific Syntax Exception used when a - given field has a pre-defined range or a invalid filter - criteria combination is requested - value: - status: 400 - code: OUT_OF_RANGE - message: Client specified an invalid range. - - 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 and a new - authentication is required - value: - status: 401 - code: UNAUTHENTICATED - message: Request not authenticated due to missing, invalid, - or expired credentials. A new authentication is required. - - 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 - - INVALID_TOKEN_CONTEXT - 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. - GENERIC_403_INVALID_TOKEN_CONTEXT: - description: Reflect some inconsistency between information in - some field of the API and the related OAuth2 Token - value: - status: 403 - code: INVALID_TOKEN_CONTEXT - message: "{{field}} is not consistent with access token." - - 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. - Generic422: description: Unprocessable Content headers: @@ -696,7 +526,7 @@ components: application/json: schema: allOf: - - $ref: "#/components/schemas/ErrorInfo" + - $ref: "../common/CAMARA_common.yaml#/components/schemas/ErrorInfo" - type: object properties: status: @@ -722,38 +552,3 @@ components: status: 422 code: UNIDENTIFIABLE_APPLICATION_PROFILE message: The Application Profile cannot be identified - - 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. diff --git a/documentation/API_documentation/Application-Endpoint-Registration-API-Readiness-Checklist.md b/documentation/API_documentation/Application-Endpoint-Registration-API-Readiness-Checklist.md deleted file mode 100644 index c00d953..0000000 --- a/documentation/API_documentation/Application-Endpoint-Registration-API-Readiness-Checklist.md +++ /dev/null @@ -1,19 +0,0 @@ -# Application Endpoints Registration API Readiness minimum criteria checklist - -Checklist for Application-Endpoint-Registration v0.1.0 - -| 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/application-endpoint-registration.yaml) | -| 2 | Design guidelines from Commonalities applied | O | M | M | M | Y | [r3.3](https://github.com/camaraproject/Commonalities/releases/tag/r3.3) | -| 3 | Guidelines from ICM applied | O | M | M | M | Y | [r3.3](https://github.com/camaraproject/IdentityAndConsentManagement/releases/tag/r3.3) | -| 4 | API versioning convention applied | M | M | M | M | Y | | -| 5 | API documentation | M | M | M | M | Y | inline in YAML | -| 6 | User stories | O | O | O | M | Y | [link](/documentation/API_documentation/application-endpoint-registration-User-Story.md) | -| 7 | Basic API test cases & documentation | O | M | M | M | Y | [link](/code/Test_definitions/application-endpoint-registration.feature) | -| 8 | Enhanced API test cases & documentation | O | O | O | M | N | | -| 9 | Test result statement | O | O | O | M | N | | -| 10 | API release numbering convention applied | M | M | M | M | Y | | -| 11 | Change log updated | M | M | M | M | Y | [link](/CHANGELOG.md) | -| 12 | Previous public release was certified | O | O | O | M | N | | -| 13 | API description (for marketing) | O | O | M | M | Y | [Wiki link](https://lf-camaraproject.atlassian.net/wiki/x/dAAsC) | From 67a0801fef2ca0110d57ea7370ea4f0eb0362441 Mon Sep 17 00:00:00 2001 From: maheshc01 Date: Mon, 20 Jul 2026 13:30:07 -0500 Subject: [PATCH 2/2] fix: add pattern constraints to free-text string fields (S-313) --- code/API_definitions/application-endpoint-registration.yaml | 3 +++ 1 file changed, 3 insertions(+) diff --git a/code/API_definitions/application-endpoint-registration.yaml b/code/API_definitions/application-endpoint-registration.yaml index 42e6e2b..a75e827 100644 --- a/code/API_definitions/application-endpoint-registration.yaml +++ b/code/API_definitions/application-endpoint-registration.yaml @@ -333,11 +333,13 @@ components: applicationProviderName: type: string maxLength: 256 + pattern: ^[^\r\n]*$ description: Name of the Application Provider example: "AppProvider" applicationDescription: type: string maxLength: 2048 + pattern: ^[^\r\n]*$ description: Description of the application. example: "This is a V2X application." applicationProfileId: @@ -401,6 +403,7 @@ components: applicationEndpointDescription: type: string maxLength: 2048 + pattern: ^[^\r\n]*$ description: Description of the application endpoint example: "V2X app deployed at ZoneA"