diff --git a/code/API_definitions/Application-endpoint-registration.yaml b/code/API_definitions/Application-endpoint-registration.yaml new file mode 100644 index 0000000..3ce2ef3 --- /dev/null +++ b/code/API_definitions/Application-endpoint-registration.yaml @@ -0,0 +1,625 @@ +--- +openapi: 3.0.3 +info: + title: Application Endpoints Registration + description: | + The Application Endpoints Registration API provides a programmable + interface for developers to register the endpoints of an application + which is deployed across various Edge Cloud Zones. + It allows developers to retrieve, update, and delete those registrations. + + # Introduction + + The API registers the Edge 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. + + # Relevant terms and definitions + + * **Application Endpoint**: + + The Endpoint on which the application is running. + It can be a URI, FQDN, IPv4, or IPv6 address with a port number. + + # API functionality + + The API provides 4 operations: + - POST registerApplicationEndpoints: Registers the Application Endpoints + 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 + Applications registered to a specified applicationEndpointId. + - PUT updateApplicationEndpoint: Update registered application endpoint + information. + - DELETE deregisterApplicationEndpoint: Deregister an application's + application Endpoint from the edge cloud zone. + + # Authorization and authentication + + The "Camara Security and Interoperability Profile" provides details on + how a client requests an access token. Please refer to Identify and + Consent Management + (https://github.com/camaraproject/IdentityAndConsentManagement/) + for the released version of the Profile. + + Which specific authorization flows are to be used will be determined + during onboarding process, happening between the API Client and the + Telco Operator exposing the API, taking into account the declared + purpose for accessing the API, while also being subject to the prevailing + legal framework dictated by local legislation. + + It is important to remark that in cases where personal user 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 3-legged access + tokens becomes mandatory. This measure ensures that the API remains in + strict compliance with user privacy preferences and regulatory obligations, + upholding the principles of transparency and user-centric data control. + + # 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) + + version: 0.1.0 + contact: + email: sp-edc@lists.camaraproject.org + license: + name: Apache 2.0 + url: https://www.apache.org/licenses/LICENSE-2.0.html + x-camara-commonalities: 0.4.0 +externalDocs: + description: Project documentation at Camara + url: https://github.com/camaraproject/EdgeCloud + +servers: + - url: "{apiRoot}/application-endpoint-registration/v0.1" + variables: + apiRoot: + default: http://localhost:9091 + description: | + API root, defined by service provider, e.g. + `api.example.com` or `api.example.com/somepath` + +tags: + - name: Application Endpoint Registration + description: | + Operations to register, read and manage deployed instances of the + application. + +paths: + /application-endpoints: + post: + security: + - openId: + - application-endpoint-registration:application-endpoints:write + tags: + - Application Endpoint Registration + summary: Register endpoints of a deployed application + description: | + Register the endpoints of a deployed application + to a specified edge cloud zone. + operationId: registerApplicationEndpoints + parameters: + - $ref: "#/components/parameters/x-correlator" + requestBody: + description: Array of Application Endpoints for a + deployed application + required: true + content: + application/json: + schema: + type: array + minItems: 1 + items: + $ref: "#/components/schemas/ApplicationEndpointRequest" + responses: + "200": + description: Returns an applicationEndpointsId + headers: + x-correlator: + $ref: '#/components/headers/x-correlator' + content: + application/json: + schema: + $ref: "#/components/schemas/ApplicationEndpointsId" + "400": + $ref: "#/components/responses/Generic400" + "401": + $ref: "#/components/responses/Generic401" + "403": + $ref: "#/components/responses/Generic403" + "404": + $ref: "#/components/responses/Generic404" + "422": + $ref: "#/components/responses/Generic422" + "500": + $ref: "#/components/responses/Generic500" + "503": + $ref: "#/components/responses/Generic503" + "504": + $ref: "#/components/responses/Generic504" + get: + security: + - openId: + - application-endpoint-registration:application-endpoints:read + tags: + - Application Endpoint Registration + summary: Get all registered edge application endpoint information + description: | + Returns endpoint information for all + Application Endpoints registered. + operationId: getAllRegisteredApplicationEndpoints + parameters: + - $ref: "#/components/parameters/x-correlator" + responses: + "200": + description: Array of registered Application Endpoints + headers: + x-correlator: + $ref: '#/components/headers/x-correlator' + content: + application/json: + schema: + type: array + items: + $ref: "#/components/schemas/ApplicationEndpoints" + "400": + $ref: "#/components/responses/Generic400" + "401": + $ref: "#/components/responses/Generic401" + "403": + $ref: "#/components/responses/Generic403" + "404": + $ref: "#/components/responses/Generic404" + "422": + $ref: "#/components/responses/Generic422" + "500": + $ref: "#/components/responses/Generic500" + "503": + $ref: "#/components/responses/Generic503" + "504": + $ref: "#/components/responses/Generic504" + + "/application-endpoints/{applicationEndpointsId}": + parameters: + - name: applicationEndpointsId + in: path + required: true + description: The unique identifier for the application endpoints + schema: + $ref: "#/components/schemas/ApplicationEndpointsId" + - $ref: "#/components/parameters/x-correlator" + get: + security: + - openId: + - application-endpoint-registration:application-endpoints:read + tags: + - Application Endpoint Registration + summary: Get registered edge application endpoint information + description: | + Returns endpoint information for all + Application Endpoints registered to a + specified applicationEndpointId. + operationId: getApplicationEndpointsById + responses: + "200": + description: Array of registered Application Endpoints + headers: + x-correlator: + $ref: '#/components/headers/x-correlator' + content: + application/json: + schema: + $ref: "#/components/schemas/ApplicationEndpoints" + "400": + $ref: "#/components/responses/Generic400" + "401": + $ref: "#/components/responses/Generic401" + "403": + $ref: "#/components/responses/Generic403" + "404": + $ref: "#/components/responses/Generic404" + "422": + $ref: "#/components/responses/Generic422" + "500": + $ref: "#/components/responses/Generic500" + "503": + $ref: "#/components/responses/Generic503" + "504": + $ref: "#/components/responses/Generic504" + + put: + security: + - openId: + - application-endpoint-registration:application-endpoints:update + tags: + - Application Endpoint Registration + summary: Update an application Endpoint + description: | + Update registered application Endpoint information. + operationId: updateApplicationEndpoint + requestBody: + description: Application Endpoint information + content: + application/json: + schema: + type: array + items: + $ref: "#/components/schemas/ApplicationEndpointRequest" + responses: + "204": + description: Updates Application Endpoint Information + headers: + x-correlator: + $ref: '#/components/headers/x-correlator' + "400": + $ref: "#/components/responses/Generic400" + "401": + $ref: "#/components/responses/Generic401" + "403": + $ref: "#/components/responses/Generic403" + "404": + $ref: "#/components/responses/Generic404" + "422": + $ref: "#/components/responses/Generic422" + "500": + $ref: "#/components/responses/Generic500" + "503": + $ref: "#/components/responses/Generic503" + "504": + $ref: "#/components/responses/Generic504" + + delete: + security: + - openId: + - application-endpoint-registration:application-endpoints:delete + tags: + - Application Endpoint Registration + summary: Deregister an application Endpoint + description: | + Deregister an application's + Endpoint from the edge cloud zone. + operationId: deregisterApplicationEndpoint + responses: + "200": + description: Deregister Application Endpoint + headers: + x-correlator: + $ref: '#/components/headers/x-correlator' + "400": + $ref: "#/components/responses/Generic400" + "401": + $ref: "#/components/responses/Generic401" + "403": + $ref: "#/components/responses/Generic403" + "404": + $ref: "#/components/responses/Generic404" + "422": + $ref: "#/components/responses/Generic422" + "500": + $ref: "#/components/responses/Generic500" + "503": + $ref: "#/components/responses/Generic503" + "504": + $ref: "#/components/responses/Generic504" + +components: + securitySchemes: + openId: + description: OpenID Provider Configuration Information + type: openIdConnect + openIdConnectUrl: https://example.com/.well-known/openid-configuration + parameters: + x-correlator: + name: x-correlator + in: header + description: Correlation id for the different services + schema: + type: string + headers: + x-correlator: + description: Correlation id for the different services + schema: + type: string + + schemas: + ApplicationEndpointRequest: + description: Application instance represented + by the application Endpoint definition + type: object + properties: + applicationEndpoint: + $ref: "#/components/schemas/ResourcesApplicationEndpoint" + applicationServerProviderName: + type: string + description: Unique ID representing the Edge + Application Provider + applicationDescription: + type: string + description: Description of the application Endpoint + applicationProfileId: + $ref: "#/components/schemas/ApplicationProfileId" + edgeCloudZoneId: + $ref: "#/components/schemas/EdgeCloudZoneId" + edgeCloudZoneName: + $ref: "#/components/schemas/EdgeCloudZoneName" + edgeCloudProvider: + $ref: "#/components/schemas/EdgeCloudProvider" + edgeCloudRegionId: + $ref: "#/components/schemas/EdgeCloudRegionName" + required: + - applicationEndpoint + - applicationServerProviderName + - applicationProfileId + - edgeCloudZoneId + - edgeCloudZoneName + - edgeCloudProvider + - edgeCloudRegionId + additionalProperties: false + ApplicationEndpoints: + description: | + List of Application endpoints information + deployed across various cloud zones. + properties: + applicationEndpointsId: + $ref: "#/components/schemas/ApplicationEndpointsId" + applicationInstance: + description: | + Application Endpoint Information + type: array + items: + $ref: "#/components/schemas/ApplicationEndpointRequest" + minItems: 0 + ResourcesApplicationEndpoint: + type: object + description: Resources of the Application Endpoint + properties: + uri: + type: string + description: URI of application Endpoint if available + format: uri + fqdn: + type: string + description: FQDN of application Endpoint if available + ipv4Address: + type: string + description: IPv4 Address of application Endpoint if available + format: ipv4 + example: "203.0.113.10" + ipv6Address: + type: string + description: IPv6 Address of application Endpoint if available + format: ipv6 + example: 2001:db8:85a3:8d3:1319:8a2e:370:7344 + port: + type: integer + description: | + Port information of application Endpoint + if IPv4 or IPv6 is mentioned + anyOf: + - required: [fqdn, ipv4Address, port] + - required: [fqdn, ipv6Address, port] + example: + { + "ipv4Address": "203.0.113.10", + "port": 59765, + "fqdn": "app.test.com", + "uri": "http://app.test.com/v1/test" + } + additionalProperties: false + EdgeCloudZoneId: + description: | + Operator-issued UUID for the Edge Cloud Zone. + type: string + format: uuid + additionalProperties: false + EdgeCloudZoneName: + description: | + Edge Cloud Zone Name - the common name for the Edge Cloud Zone. + type: string + additionalProperties: false + EdgeCloudProvider: + description: | + The company name of the Edge Cloud Zone provider. + type: string + EdgeCloudRegionName: + description: | + region of the Edge Cloud Zone. + type: string + ApplicationEndpointsId: + description: | + A system-defined string identifier representing + one or more registered Application Endpoints. + type: string + format: uuid + readOnly: true + additionalProperties: false + ApplicationProfileId: + description: | + Unique identifier for a Application Profile + type: string + readOnly: false + additionalProperties: false + 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: + $ref: "#/components/schemas/ErrorInfo" + 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: + $ref: "#/components/schemas/ErrorInfo" + 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: + $ref: '#/components/schemas/ErrorInfo' + 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: applicationProfileId is not consistent with + access token + Generic404: + description: Not found + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + 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: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + examples: + GENERIC_422_NOT_SUPPORTED: + description: Not Supported + value: + status: 422 + code: NOT_SUPPORTED + message: Service not supported for this applicationProfileId + UNIDENTIFIABLE_APPLICATION_PROFILE: + description: | + The Application Profile is not included in the request + and the profile information cannot be derived + from the 3-legged access token + value: + status: 422 + code: UNIDENTIFIABLE_APPLICATION_PROFILE + message: The Application Profile cannot be identified + Generic500: + description: Internal Server Error + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + examples: + GENERIC_500_INTERNAL: + description: Problem in Server side. Regular Server Exception + value: + status: 500 + code: INTERNAL + message: Unknown server error. Typically a server bug. + Generic503: + description: Service Unavailable + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + examples: + GENERIC_503_UNAVAILABLE: + description: Service is not available. + Temporary situation usually related to maintenance process in + the server side + value: + status: 503 + code: UNAVAILABLE + message: Service Unavailable. + Generic504: + description: Gateway Timeout + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + examples: + GENERIC_504_TIMEOUT: + description: API Server Timeout + value: + status: 504 + code: TIMEOUT + message: Request timeout exceeded.