From cdb7a8acdb41bfd265fd1d4346b96dfc7019b99d Mon Sep 17 00:00:00 2001 From: maheshc01 Date: Sat, 3 Oct 2026 19:26:12 -0500 Subject: [PATCH 1/3] Align with Commonalities r4.4 - Use r4.4 catalogue responses for 400/401/403/404, local 429 - Document error conditions and use cases (#46, #47) - Use common Port and SingleIpv6Address - Update mandatory description text from r4.4 templates - Remove unrelated Mobile Connect section, fix externalDocs text - Extend test definitions to cover all operations and error codes --- .../application-endpoint-registration.yaml | 166 ++++++---- .../application-endpoint-registration.feature | 293 ++++++++++++++---- 2 files changed, 348 insertions(+), 111 deletions(-) diff --git a/code/API_definitions/application-endpoint-registration.yaml b/code/API_definitions/application-endpoint-registration.yaml index 4198eec..6294820 100644 --- a/code/API_definitions/application-endpoint-registration.yaml +++ b/code/API_definitions/application-endpoint-registration.yaml @@ -48,24 +48,78 @@ info: of a deployed application to a specified edge cloud zone. - GET getAllRegisteredApplicationEndpoints: Returns endpoint information for all registered Applications. - - GET getApplicationEndpointsByID: Returns endpoint information for all + - GET getApplicationEndpointsById: Returns endpoint information for all Applications registered to a specified applicationEndpointListId. - PUT updateApplicationEndpoint: Update registered application endpoint information. - DELETE deregisterApplicationEndpoint: Deregister an application's Endpoints. + ## Errors + + - If the request contains a formatting or any other syntactic error, or a + request body that does not comply with the schema, a `400 INVALID_ARGUMENT` + error is returned. + - If the request cannot be authenticated due to missing, invalid, or + expired credentials, a `401 UNAUTHENTICATED` error is returned. + - If the access token does not have the required scope, a + `403 PERMISSION_DENIED` error is returned. + - If the `applicationEndpointListId` does not identify registered + application endpoints, a `404 NOT_FOUND` error is returned. + - If the `applicationProfileId` in the request body does not identify an + existing application profile, a `404 NOT_FOUND` error is returned. + + # Use cases + + Application providers need to make their services discoverable when + deployed across edge infrastructure. This API allows an application + developer to register the endpoints (FQDN or IP address, and port) of + application instances deployed across different Edge Cloud Zones, update + them when necessary, and remove them when they are decommissioned. + + The registered endpoints are not consumed through this API by other + parties. Their purpose is to make the application discoverable through + the Application Endpoint Discovery API: + + - On successful registration, this API returns an + `applicationEndpointListId`. + - The application developer's server passes this identifier as + `applicationEndpointsId` when calling the Application Endpoint Discovery + API, which returns the optimal registered endpoint(s) for a given + end-user device. + - Registration is needed for applications that are not deployed through + the Edge Application Management API, for example applications deployed by + the developer directly or on a third-party Edge Cloud platform. + Applications deployed through Edge Application Management are discovered + by their `appId` instead. + + Registered endpoints are only accessible to the API client that registered + them. + + Examples of applications that benefit from registering their endpoints: + + - Gaming: multiplayer server endpoints, registered as new instances are + started, so that players connect to a nearby server. + - Video streaming: media server endpoints, so that clients find the best + available streaming source. + - IoT platforms: data processing endpoints, so that devices connect to an + available nearby service. + - AR/VR services: rendering endpoints, to provide low-latency experiences + to nearby users. + + # Additional CAMARA error responses The list of error codes in this API specification is not exhaustive. Therefore the API specification MAY not document some non-mandatory error statuses as indicated in `CAMARA API Design Guide`. - Please refer to the `CAMARA_common.yaml` of the Commonalities Release associated to this API version for a complete list of error responses. The applicable Commonalities Release can be identified in the `API Readiness Checklist` document associated to this API version. + Please refer to the `CAMARA_common.yaml` of the Commonalities Release associated to this API version for a complete list of error responses. The applicable Commonalities Release can be identified from the `x-camara-commonalities` field, the changelog and the metadata of the released API version. As a specific rule, error `501 - NOT_IMPLEMENTED` can be only a possible error response if it is explicitly documented in the API. + # 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. @@ -76,27 +130,17 @@ info: + # Request body strictness This API rejects requests with JSON request bodies that contain properties not declared in this specification, at any nesting level. Unknown properties result in a `400 INVALID_ARGUMENT` response. - # Further info and support - - [GSMA Mobile Connect Account Takeover Protection specification] - (https://www.gsma.com/identity/wp-content/uploads/2022/12/IDY.24-Mobile- - Connect-Account-Takeover-Protection-Definition-and-Technical-Requirements- - v2.0.pdf) - was used as source of input for this API. For more about Mobile Connect, - please see [Mobile Connect website](https://mobileconnect.io/). - - (FAQs will be added in a later version of the documentation) - license: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0.html externalDocs: - description: Project documentation at CAMARA + description: Product documentation at CAMARA url: https://github.com/camaraproject/ApplicationEndpointRegistration servers: @@ -146,15 +190,15 @@ paths: schema: $ref: "#/components/schemas/ApplicationEndpointListId" "400": - $ref: "../common/CAMARA_common.yaml#/components/responses/Generic400" + $ref: "../common/CAMARA_common.yaml#/components/responses/BadRequest400" "401": - $ref: "../common/CAMARA_common.yaml#/components/responses/Generic401" + $ref: "../common/CAMARA_common.yaml#/components/responses/Unauthenticated401" "403": - $ref: "../common/CAMARA_common.yaml#/components/responses/Generic403" + $ref: "../common/CAMARA_common.yaml#/components/responses/PermissionDenied403" "404": - $ref: "../common/CAMARA_common.yaml#/components/responses/Generic404" + $ref: "../common/CAMARA_common.yaml#/components/responses/NotFound404" "429": - $ref: "../common/CAMARA_common.yaml#/components/responses/Generic429" + $ref: "#/components/responses/EndpointRegistrationTooManyRequests429" get: security: - openId: @@ -182,13 +226,13 @@ paths: items: $ref: "#/components/schemas/ApplicationEndpointList" "400": - $ref: "../common/CAMARA_common.yaml#/components/responses/Generic400" + $ref: "../common/CAMARA_common.yaml#/components/responses/BadRequest400" "401": - $ref: "../common/CAMARA_common.yaml#/components/responses/Generic401" + $ref: "../common/CAMARA_common.yaml#/components/responses/Unauthenticated401" "403": - $ref: "../common/CAMARA_common.yaml#/components/responses/Generic403" + $ref: "../common/CAMARA_common.yaml#/components/responses/PermissionDenied403" "429": - $ref: "../common/CAMARA_common.yaml#/components/responses/Generic429" + $ref: "#/components/responses/EndpointRegistrationTooManyRequests429" "/application-endpoint-lists/{applicationEndpointListId}": parameters: @@ -223,15 +267,15 @@ paths: schema: $ref: "#/components/schemas/ApplicationEndpointList" "400": - $ref: "../common/CAMARA_common.yaml#/components/responses/Generic400" + $ref: "../common/CAMARA_common.yaml#/components/responses/BadRequest400" "401": - $ref: "../common/CAMARA_common.yaml#/components/responses/Generic401" + $ref: "../common/CAMARA_common.yaml#/components/responses/Unauthenticated401" "403": - $ref: "../common/CAMARA_common.yaml#/components/responses/Generic403" + $ref: "../common/CAMARA_common.yaml#/components/responses/PermissionDenied403" "404": - $ref: "../common/CAMARA_common.yaml#/components/responses/Generic404" + $ref: "../common/CAMARA_common.yaml#/components/responses/NotFound404" "429": - $ref: "../common/CAMARA_common.yaml#/components/responses/Generic429" + $ref: "#/components/responses/EndpointRegistrationTooManyRequests429" put: security: @@ -257,15 +301,15 @@ paths: x-correlator: $ref: '#/components/headers/x-correlator' "400": - $ref: "../common/CAMARA_common.yaml#/components/responses/Generic400" + $ref: "../common/CAMARA_common.yaml#/components/responses/BadRequest400" "401": - $ref: "../common/CAMARA_common.yaml#/components/responses/Generic401" + $ref: "../common/CAMARA_common.yaml#/components/responses/Unauthenticated401" "403": - $ref: "../common/CAMARA_common.yaml#/components/responses/Generic403" + $ref: "../common/CAMARA_common.yaml#/components/responses/PermissionDenied403" "404": - $ref: "../common/CAMARA_common.yaml#/components/responses/Generic404" + $ref: "../common/CAMARA_common.yaml#/components/responses/NotFound404" "429": - $ref: "../common/CAMARA_common.yaml#/components/responses/Generic429" + $ref: "#/components/responses/EndpointRegistrationTooManyRequests429" delete: security: @@ -285,15 +329,15 @@ paths: x-correlator: $ref: '#/components/headers/x-correlator' "400": - $ref: "../common/CAMARA_common.yaml#/components/responses/Generic400" + $ref: "../common/CAMARA_common.yaml#/components/responses/BadRequest400" "401": - $ref: "../common/CAMARA_common.yaml#/components/responses/Generic401" + $ref: "../common/CAMARA_common.yaml#/components/responses/Unauthenticated401" "403": - $ref: "../common/CAMARA_common.yaml#/components/responses/Generic403" + $ref: "../common/CAMARA_common.yaml#/components/responses/PermissionDenied403" "404": - $ref: "../common/CAMARA_common.yaml#/components/responses/Generic404" + $ref: "../common/CAMARA_common.yaml#/components/responses/NotFound404" "429": - $ref: "../common/CAMARA_common.yaml#/components/responses/Generic429" + $ref: "#/components/responses/EndpointRegistrationTooManyRequests429" components: securitySchemes: @@ -383,9 +427,9 @@ components: ipv4Address: $ref: "../common/CAMARA_common.yaml#/components/schemas/SingleIpv4Address" ipv6Address: - $ref: "#/components/schemas/SingleIpv6Addr" + $ref: "../common/CAMARA_common.yaml#/components/schemas/SingleIpv6Address" port: - $ref: "#/components/schemas/Port" + $ref: "../common/CAMARA_common.yaml#/components/schemas/Port" edgeCloudZone: $ref: "#/components/schemas/EdgeCloudZone" applicationEndpointDescription: @@ -489,20 +533,28 @@ components: minLength: 4 example: "app.example.com" - 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 1-65535. - type: integer - format: int32 - minimum: 1 - maximum: 65535 - example: 8080 + responses: + EndpointRegistrationTooManyRequests429: + description: Too Many Requests + headers: + x-correlator: + $ref: "../common/CAMARA_common.yaml#/components/headers/x-correlator" + content: + application/json: + schema: + allOf: + - $ref: "../common/CAMARA_common.yaml#/components/schemas/ErrorInfo" + - type: object + properties: + status: + enum: + - 429 + code: + enum: + - QUOTA_EXCEEDED + - TOO_MANY_REQUESTS + examples: + GENERIC_429_QUOTA_EXCEEDED: + $ref: "../common/CAMARA_common.yaml#/components/examples/GENERIC_429_QUOTA_EXCEEDED" + GENERIC_429_TOO_MANY_REQUESTS: + $ref: "../common/CAMARA_common.yaml#/components/examples/GENERIC_429_TOO_MANY_REQUESTS" diff --git a/code/Test_definitions/application-endpoint-registration.feature b/code/Test_definitions/application-endpoint-registration.feature index 6852505..621c596 100644 --- a/code/Test_definitions/application-endpoint-registration.feature +++ b/code/Test_definitions/application-endpoint-registration.feature @@ -1,89 +1,274 @@ - @Application_Endpoint_Registration -Feature: CAMARA Application Endpoint Registration API, vwip - Operations for registering application endpoints - -# Input to be provided by the implementation to the tests -# * apiRoot: API root of the server URL -# References to OAS spec schemas refer to schemas specified in application-endpoint-registration.yaml + @application_endpoint_registration +Feature: CAMARA Application Endpoint Registration API, vwip - Operations registerApplicationEndpoints, getAllRegisteredApplicationEndpoints, getApplicationEndpointsById, updateApplicationEndpoint, deregisterApplicationEndpoint + # Input to be provided by the implementation to the tester + # + # Implementation indications: + # * apiRoot: API root of the server URL + # + # Testing assets: + # * An applicationProfileId identifying an existing application profile. + # * An applicationEndpointListId identifying existing registered application endpoints, created by the API client used for testing. + # + # References to OAS spec schemas refer to schemas specified in application-endpoint-registration.yaml Background: Common Application Endpoint Registration setup Given an environment at "apiRoot" - And the resource "/application-endpoint-registration/vwip" + And the resource "/application-endpoint-registration/vwip/application-endpoint-lists" as base-url And the header "Content-Type" is set to "application/json" And the header "Authorization" is set to a valid access token And the header "x-correlator" complies with the schema at "#/components/schemas/XCorrelator" -######### Happy Path Scenarios ################################# + # Success scenarios - @application_endpoint_registration_01_register_app_endpoints - Scenario: Register a new application endpoint - Given a valid application endpoint registration request body + @application_endpoint_registration_register_01_success + Scenario: Register application endpoints + Given the request body is set to a request body compliant with the schema at "#/components/schemas/ApplicationEndpointsInfo" + And the request body property "$.applicationProfileId" is set to a value identifying an existing application profile When the request "registerApplicationEndpoints" is sent - Then the response code is 200 + Then the response status code is 200 And the response header "Content-Type" is "application/json" And the response header "x-correlator" has same value as the request header "x-correlator" - And the response body complies with the OAS schema at "/components/schemas/ApplicationEndpointListId" - And the response contains a valid application endpoint ID + And the response body complies with the OAS schema at "#/components/schemas/ApplicationEndpointListId" - @application_endpoint_registration_02_get_all_app_endpoints + @application_endpoint_registration_getAll_01_success Scenario: Retrieve all registered application endpoints When the request "getAllRegisteredApplicationEndpoints" is sent - Then the response code is 200 + Then the response status code is 200 And the response header "Content-Type" is "application/json" And the response header "x-correlator" has same value as the request header "x-correlator" - And the response body complies with the OAS schema at "/components/schemas/ApplicationEndpointList" - And the response contains a list of application endpoints + And the response body is an array of at most 20 elements, each complying with the OAS schema at "#/components/schemas/ApplicationEndpointList" - @application_endpoint_registration_03_get_app_endpoint - Scenario: Retrieve existing application endpoint details - Given an application endpoint ID for an existing registered endpoint + @application_endpoint_registration_getById_01_success + Scenario: Retrieve registered application endpoints by identifier + Given the path parameter "applicationEndpointListId" is set to a value identifying existing registered application endpoints When the request "getApplicationEndpointsById" is sent - Then the response code is 200 + Then the response status code is 200 And the response header "Content-Type" is "application/json" And the response header "x-correlator" has same value as the request header "x-correlator" - And the response body complies with the OAS schema at "/components/schemas/ApplicationEndpointList" - And the response contains the correct application endpoint details + And the response body complies with the OAS schema at "#/components/schemas/ApplicationEndpointList" + And the response property "$.applicationEndpointListId" has same value as the path parameter "applicationEndpointListId" - @application_endpoint_registration_04_update_app_endpoint - Scenario: Update an existing application endpoint - Given an application endpoint ID for an existing registered endpoint - And a valid application endpoint update request body + @application_endpoint_registration_update_01_success + Scenario: Update registered application endpoints + Given the path parameter "applicationEndpointListId" is set to a value identifying existing registered application endpoints + And the request body is set to a request body compliant with the schema at "#/components/schemas/ApplicationEndpointsInfo" When the request "updateApplicationEndpoint" is sent - Then the response code is 204 + Then the response status code is 204 And the response header "x-correlator" has same value as the request header "x-correlator" - @application_endpoint_registration_05_delete_app_endpoint - Scenario: Delete an existing application endpoint - Given an application endpoint ID for an existing registered endpoint + @application_endpoint_registration_update_02_changes_returned + Scenario: Updated application endpoints are returned on retrieval + Given the path parameter "applicationEndpointListId" is set to a value identifying existing registered application endpoints + And the request "updateApplicationEndpoint" has been sent with a request body compliant with the schema at "#/components/schemas/ApplicationEndpointsInfo" + When the request "getApplicationEndpointsById" is sent + Then the response status code is 200 + And the response property "$.applicationEndpointsInfo" has the values sent in the update request body + + @application_endpoint_registration_deregister_01_success + Scenario: Deregister application endpoints + Given the path parameter "applicationEndpointListId" is set to a value identifying existing registered application endpoints When the request "deregisterApplicationEndpoint" is sent - Then the response code is 204 + Then the response status code is 204 And the response header "x-correlator" has same value as the request header "x-correlator" -######### Error Scenarios ################################# + @application_endpoint_registration_deregister_02_not_found_after_deregistration + Scenario: Deregistered application endpoints can no longer be retrieved + Given the path parameter "applicationEndpointListId" is set to a value identifying application endpoints that have been deregistered + When the request "getApplicationEndpointsById" is sent + Then the response status code is 404 + And the response property "$.status" is 404 + And the response property "$.code" is "NOT_FOUND" + And the response property "$.message" contains a user friendly text + + # Error code 400 + + @application_endpoint_registration_400.1_no_request_body + Scenario Outline: Missing request body + Given the path parameter "applicationEndpointListId" is set to a value identifying existing registered application endpoints, if required by the operation + And the request body is not included + When the request "" is sent + Then the response status code is 400 + And the response property "$.status" is 400 + And the response property "$.code" is "INVALID_ARGUMENT" + And the response property "$.message" contains a user friendly text + + Examples: + | operationId | + | registerApplicationEndpoints | + | updateApplicationEndpoint | + + @application_endpoint_registration_400.2_empty_request_body + Scenario Outline: Empty object as request body + Given the path parameter "applicationEndpointListId" is set to a value identifying existing registered application endpoints, if required by the operation + And the request body is set to "{}" + When the request "" is sent + Then the response status code is 400 + And the response property "$.status" is 400 + And the response property "$.code" is "INVALID_ARGUMENT" + And the response property "$.message" contains a user friendly text + + Examples: + | operationId | + | registerApplicationEndpoints | + | updateApplicationEndpoint | - @application_endpoint_registration_06_invalid_registration - Scenario: Register application endpoint with invalid data - Given an invalid application endpoint registration request body + @application_endpoint_registration_400.3_required_input_properties_missing + Scenario Outline: Required input properties are missing + Given the request body is set to a request body compliant with the schema at "#/components/schemas/ApplicationEndpointsInfo" + And the request body property "" is not included When the request "registerApplicationEndpoints" is sent - Then the response code is 400 - And the response header "Content-Type" is "application/json" - And the response body complies with the OAS schema at "/components/schemas/ErrorInfo" + Then the response status code is 400 + And the response property "$.status" is 400 And the response property "$.code" is "INVALID_ARGUMENT" + And the response property "$.message" contains a user friendly text - @application_endpoint_registration_07_endpoint_not_found - Scenario: Retrieve non-existing application endpoint - Given an application endpoint ID that doesn't exist - When the request "getApplicationEndpointsById" is sent - Then the response code is 404 - And the response header "Content-Type" is "application/json" - And the response body complies with the OAS schema at "/components/schemas/ErrorInfo" - And the response property "$.code" is "NOT_FOUND" + Examples: + | input_property | + | $.applicationEndpoints | + | $.applicationProviderName | + | $.applicationProfileId | + | $.applicationEndpoints[0].port | + + @application_endpoint_registration_400.4_input_properties_schema_not_compliant + Scenario Outline: Input property values do not comply with the schema + Given the request body is set to a request body compliant with the schema at "#/components/schemas/ApplicationEndpointsInfo" + And the request body property "" does not comply with the OAS schema at "" + When the request "registerApplicationEndpoints" is sent + Then the response status code is 400 + And the response property "$.status" is 400 + And the response property "$.code" is "INVALID_ARGUMENT" + And the response property "$.message" contains a user friendly text + + Examples: + | input_property | oas_spec_schema | + | $.applicationProfileId | #/components/schemas/ApplicationProfileId | + | $.applicationEndpoints[0].port | #/components/schemas/Port | + | $.applicationEndpoints[0].domainName | #/components/schemas/DomainName | + | $.applicationEndpoints[0].ipv4Address | #/components/schemas/SingleIpv4Address | + | $.applicationEndpoints[0].ipv6Address | #/components/schemas/SingleIpv6Address | - @application_endpoint_registration_08_unauthenticated - Scenario: Register application endpoint without authentication - Given a valid application endpoint registration request body - And the header "Authorization" is not present + @application_endpoint_registration_400.5_no_endpoint_address + Scenario: Application endpoint without domainName, ipv4Address or ipv6Address + Given the request body is set to a request body compliant with the schema at "#/components/schemas/ApplicationEndpointsInfo" + And the request body property "$.applicationEndpoints[0]" includes neither "domainName", "ipv4Address" nor "ipv6Address" When the request "registerApplicationEndpoints" is sent - Then the response code is 401 + Then the response status code is 400 + And the response property "$.status" is 400 + And the response property "$.code" is "INVALID_ARGUMENT" + And the response property "$.message" contains a user friendly text + + @application_endpoint_registration_400.6_invalid_path_parameter + Scenario Outline: Path parameter does not comply with the schema + Given the path parameter "applicationEndpointListId" does not comply with the OAS schema at "#/components/schemas/ApplicationEndpointListId" + When the request "" is sent + Then the response status code is 400 + And the response property "$.status" is 400 + And the response property "$.code" is "INVALID_ARGUMENT" + And the response property "$.message" contains a user friendly text + + Examples: + | operationId | + | getApplicationEndpointsById | + | updateApplicationEndpoint | + | deregisterApplicationEndpoint | + + @application_endpoint_registration_400.7_invalid_x-correlator + Scenario: Invalid x-correlator value + Given the header "x-correlator" does not comply with the OAS schema at "#/components/schemas/XCorrelator" + When the request "getAllRegisteredApplicationEndpoints" is sent + Then the response status code is 400 + And the response property "$.status" is 400 + And the response property "$.code" is "INVALID_ARGUMENT" + And the response property "$.message" contains a user friendly text + + # Error code 401 + + @application_endpoint_registration_401.1_no_authorization_header + Scenario: No Authorization header + Given the header "Authorization" is removed + When the request "getAllRegisteredApplicationEndpoints" is sent + Then the response status code is 401 + And the response property "$.status" is 401 + And the response property "$.code" is "UNAUTHENTICATED" + And the response property "$.message" contains a user friendly text + + @application_endpoint_registration_401.2_expired_access_token + Scenario: Expired access token + Given the header "Authorization" is set to an expired access token + When the request "getAllRegisteredApplicationEndpoints" is sent + Then the response status code is 401 + And the response property "$.status" is 401 + And the response property "$.code" is "UNAUTHENTICATED" + And the response property "$.message" contains a user friendly text + + @application_endpoint_registration_401.3_invalid_access_token + Scenario: Invalid access token + Given the header "Authorization" is set to an invalid access token + When the request "getAllRegisteredApplicationEndpoints" is sent + Then the response status code is 401 And the response header "Content-Type" is "application/json" - And the response body complies with the OAS schema at "/components/schemas/ErrorInfo" + And the response property "$.status" is 401 And the response property "$.code" is "UNAUTHENTICATED" + And the response property "$.message" contains a user friendly text + + # Error code 403 + + @application_endpoint_registration_403.1_missing_scope_collection + Scenario Outline: Missing scope in the access token for collection operations + Given the header "Authorization" is set to an access token without the required scope "" + And the request body is set to a valid request body, if required by the operation + When the request "" is sent + Then the response status code is 403 + And the response property "$.status" is 403 + And the response property "$.code" is "PERMISSION_DENIED" + And the response property "$.message" contains a user friendly text + + Examples: + | operationId | scope | + | registerApplicationEndpoints | application-endpoint-registration:application-endpoints:write | + | getAllRegisteredApplicationEndpoints | application-endpoint-registration:application-endpoints:read | + + @application_endpoint_registration_403.2_missing_scope_item + Scenario Outline: Missing scope in the access token for operations on registered application endpoints + Given the header "Authorization" is set to an access token without the required scope "" + And the path parameter "applicationEndpointListId" is set to a value identifying existing registered application endpoints + And the request body is set to a valid request body, if required by the operation + When the request "" is sent + Then the response status code is 403 + And the response property "$.status" is 403 + And the response property "$.code" is "PERMISSION_DENIED" + And the response property "$.message" contains a user friendly text + + Examples: + | operationId | scope | + | getApplicationEndpointsById | application-endpoint-registration:application-endpoints:read | + | updateApplicationEndpoint | application-endpoint-registration:application-endpoints:update | + | deregisterApplicationEndpoint | application-endpoint-registration:application-endpoints:delete | + + # Error code 404 + + @application_endpoint_registration_404.1_application_endpoint_list_not_found + Scenario Outline: The applicationEndpointListId does not identify registered application endpoints + Given the path parameter "applicationEndpointListId" is compliant with the schema but does not identify registered application endpoints + And the request body is set to a valid request body, if required by the operation + When the request "" is sent + Then the response status code is 404 + And the response property "$.status" is 404 + And the response property "$.code" is "NOT_FOUND" + And the response property "$.message" contains a user friendly text + + Examples: + | operationId | + | getApplicationEndpointsById | + | updateApplicationEndpoint | + | deregisterApplicationEndpoint | + + @application_endpoint_registration_404.2_application_profile_not_found + Scenario: The applicationProfileId does not identify an existing application profile + Given the request body is set to a request body compliant with the schema at "#/components/schemas/ApplicationEndpointsInfo" + And the request body property "$.applicationProfileId" is compliant with the schema but does not identify an existing application profile + When the request "registerApplicationEndpoints" is sent + Then the response status code is 404 + And the response property "$.status" is 404 + And the response property "$.code" is "NOT_FOUND" + And the response property "$.message" contains a user friendly text From 090c66f5281a3093203b0cddcd0cd631ba6d5399 Mon Sep 17 00:00:00 2001 From: maheshc01 Date: Sat, 3 Oct 2026 19:35:31 -0500 Subject: [PATCH 2/3] Move use case explanation into Introduction --- .../application-endpoint-registration.yaml | 74 +++++++------------ 1 file changed, 28 insertions(+), 46 deletions(-) diff --git a/code/API_definitions/application-endpoint-registration.yaml b/code/API_definitions/application-endpoint-registration.yaml index 6294820..8ae90be 100644 --- a/code/API_definitions/application-endpoint-registration.yaml +++ b/code/API_definitions/application-endpoint-registration.yaml @@ -12,14 +12,34 @@ info: # Introduction - The API registers the Application Endpoints. - This information can be used for various use cases like optimal endpoint - discovery to help end users connect to the most optimal instance of the - application which is distributed across various Edge Cloud Zones. - Additionally the information can be used to monitor the edge instances to - take decisions from a lifecycle management perspective. The API provides - the ability to register, read and manage the deployed edge instances of - the application. + Application providers need to make their services discoverable when + deployed across edge infrastructure. This API allows an application + developer to register the endpoints (FQDN or IP address, and port) of + application instances deployed across different Edge Cloud Zones, update + them when necessary, and remove them when they are decommissioned. + + The registered endpoints are not consumed through this API by other + parties. Their purpose is to make the application discoverable through + the Application Endpoint Discovery API: + + - On successful registration, this API returns an + `applicationEndpointListId`. + - The application developer's server passes this identifier as + `applicationEndpointsId` when calling the Application Endpoint Discovery + API, which returns the optimal registered endpoint(s) for a given + end-user device. + - Registration is needed for applications that are not deployed through + the Edge Application Management API, for example applications deployed by + the developer directly or on a third-party Edge Cloud platform. + Applications deployed through Edge Application Management are discovered + by their `appId` instead. + + Additionally, the registered information can be used to monitor the edge + instances of the application to take decisions from a lifecycle + management perspective. + + Registered endpoints are only accessible to the API client that registered + them. # Relevant terms and definitions @@ -69,44 +89,6 @@ info: - If the `applicationProfileId` in the request body does not identify an existing application profile, a `404 NOT_FOUND` error is returned. - # Use cases - - Application providers need to make their services discoverable when - deployed across edge infrastructure. This API allows an application - developer to register the endpoints (FQDN or IP address, and port) of - application instances deployed across different Edge Cloud Zones, update - them when necessary, and remove them when they are decommissioned. - - The registered endpoints are not consumed through this API by other - parties. Their purpose is to make the application discoverable through - the Application Endpoint Discovery API: - - - On successful registration, this API returns an - `applicationEndpointListId`. - - The application developer's server passes this identifier as - `applicationEndpointsId` when calling the Application Endpoint Discovery - API, which returns the optimal registered endpoint(s) for a given - end-user device. - - Registration is needed for applications that are not deployed through - the Edge Application Management API, for example applications deployed by - the developer directly or on a third-party Edge Cloud platform. - Applications deployed through Edge Application Management are discovered - by their `appId` instead. - - Registered endpoints are only accessible to the API client that registered - them. - - Examples of applications that benefit from registering their endpoints: - - - Gaming: multiplayer server endpoints, registered as new instances are - started, so that players connect to a nearby server. - - Video streaming: media server endpoints, so that clients find the best - available streaming source. - - IoT platforms: data processing endpoints, so that devices connect to an - available nearby service. - - AR/VR services: rendering endpoints, to provide low-latency experiences - to nearby users. - # Additional CAMARA error responses From c67c7a633b4d8e6bc34a91cf742f6e30e4cbf4f8 Mon Sep 17 00:00:00 2001 From: maheshc01 Date: Sat, 3 Oct 2026 19:40:14 -0500 Subject: [PATCH 3/3] Keep original introduction text and usage examples --- .../application-endpoint-registration.yaml | 22 ++++++++++++++++--- 1 file changed, 19 insertions(+), 3 deletions(-) diff --git a/code/API_definitions/application-endpoint-registration.yaml b/code/API_definitions/application-endpoint-registration.yaml index 8ae90be..7734f23 100644 --- a/code/API_definitions/application-endpoint-registration.yaml +++ b/code/API_definitions/application-endpoint-registration.yaml @@ -18,6 +18,15 @@ info: application instances deployed across different Edge Cloud Zones, update them when necessary, and remove them when they are decommissioned. + The API registers the Application Endpoints. + This information can be used for various use cases like optimal endpoint + discovery to help end users connect to the most optimal instance of the + application which is distributed across various Edge Cloud Zones. + Additionally the information can be used to monitor the edge instances to + take decisions from a lifecycle management perspective. The API provides + the ability to register, read and manage the deployed edge instances of + the application. + The registered endpoints are not consumed through this API by other parties. Their purpose is to make the application discoverable through the Application Endpoint Discovery API: @@ -34,9 +43,16 @@ info: Applications deployed through Edge Application Management are discovered by their `appId` instead. - Additionally, the registered information can be used to monitor the edge - instances of the application to take decisions from a lifecycle - management perspective. + Application Endpoint Registration could be useful in scenarios such as: + + - Gaming: multiplayer server endpoints, registered as new instances are + started, so that players connect to a nearby server. + - Video streaming: media server endpoints, so that clients find the best + available streaming source. + - IoT platforms: data processing endpoints, so that devices connect to an + available nearby service. + - AR/VR services: rendering endpoints, to provide low-latency experiences + to nearby users. Registered endpoints are only accessible to the API client that registered them.