application end point registration API yaml #321
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,392 @@ | ||
| openapi: 3.0.3 | ||
| info: | ||
| title: Application Endpoint Registration API | ||
| version: 0.1.0 | ||
| license: | ||
| name: Apache 2.0 | ||
| url: https://www.apache.org/licenses/LICENSE-2.0.html | ||
| description: | | ||
| Application endpoint registration allows application developers to | ||
| register one or more Application Endpoints, and retrieve, update,and | ||
|
There was a problem hiding this comment. update,and -> update, and |
||
| delete those registrations. | ||
|
|
||
| This information can we used for various usecases like optimal end | ||
| point discovery to help end users connect to the most most optimal | ||
|
There was a problem hiding this comment. "most most optimal" should be changed to "most optimal" |
||
| instance of the application. Addtionally the information can be used | ||
|
There was a problem hiding this comment. I feel that if can refer or qualify applications as "edge applications" then it will make it more related to edge deployments while using generically may imply any deployment including clouds. Just a thought. There was a problem hiding this comment. Addtionally -> Additionally |
||
| to also monitor the different instance to take decisions from a lifecycle | ||
| management perspective. | ||
|
|
||
| ### 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. | ||
|
|
||
| x-camara-commonalities: 0.4.0 | ||
|
|
||
| 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 an deployed instances of the | ||
|
There was a problem hiding this comment.
There was a problem hiding this comment. Modified to "read and manage deployed instances" |
||
| application. | ||
|
|
||
| paths: | ||
| /application-endpoints: | ||
|
There was a problem hiding this comment. I would have expected there to also be a There was a problem hiding this comment. Agreed. Added GetAll api which lists all the registered applications. |
||
| post: | ||
| operationId: register-application-endpoints | ||
|
There was a problem hiding this comment. For the POST method should we also include "x-correlator" header as done with other APIs.? There was a problem hiding this comment. Included "x-correlator" for all the APIs There was a problem hiding this comment. I would suggest to specify operationIds in camelCase, rather than dash-separated, i.e. this should be |
||
| requestBody: | ||
| description: Array of Application Endpoints for a | ||
| deployed application | ||
| content: | ||
| application/json: | ||
| schema: | ||
| type: array | ||
| items: | ||
| $ref: "#/components/schemas/ApplicationInstance" | ||
|
There was a problem hiding this comment. It seems like the components schema should be called There was a problem hiding this comment. Also, you probably want a |
||
| responses: | ||
| "200": | ||
|
There was a problem hiding this comment. We should also consider the additional status codes which could be valid for the POST requests in alignment with other APIs and consistency. |
||
| description: Returns a applicationEndpointsId | ||
| content: | ||
| application/json: | ||
| schema: | ||
| $ref: "#/components/schemas/TypesApplicationEndpointsId" | ||
| "401": | ||
| $ref: "#/components/responses/Unauthorized" | ||
| default: | ||
| $ref: "#/components/responses/Unexpected" | ||
| tags: | ||
| - Application Endpoint Registration | ||
| summary: Register Application Endpoints | ||
| description: Register Application Endpoints of a | ||
| deployed application to specified edge cloud zone. | ||
|
|
||
| "/application-endpoints/{applicationEndpointsId}": | ||
| parameters: | ||
| - name: applicationEndpointsId | ||
| in: path | ||
| required: true | ||
| description: applicationEndpointsId param //added desc | ||
|
There was a problem hiding this comment. This description looks like it needs to be fixed, and the |
||
| schema: | ||
| $ref: "#/components/schemas/TypesApplicationEndpointsId" | ||
| get: | ||
| operationId: get-application-endpoints-by-applicationEndpointsId | ||
| responses: | ||
| "200": | ||
| description: Arry of registered Application Endpoints | ||
| content: | ||
| application/json: | ||
| schema: | ||
| type: array | ||
| items: | ||
| $ref: "#/components/schemas/ApplicationInstance" | ||
| "400": | ||
| $ref: "#/components/responses/BadRequest" | ||
| "401": | ||
| $ref: "#/components/responses/Unauthorized" | ||
| "404": | ||
| $ref: "#/components/responses/NotFound" | ||
| default: | ||
| $ref: "#/components/responses/Unexpected" | ||
| tags: | ||
| - Application Endpoint Registration | ||
| summary: Get registered edge application endpoint information | ||
| description: Returns endpoint information for all | ||
| Application Endpoints registered to a | ||
| specified applicationEndpointId. | ||
| put: | ||
| operationId: update-application-endpoint | ||
| requestBody: | ||
| description: application Endpoint information | ||
| content: | ||
| application/json: | ||
| schema: | ||
| type: array | ||
| items: | ||
| $ref: "#/components/schemas/ApplicationInstance" | ||
| responses: | ||
| "204": | ||
| $ref: "#/components/responses/NoContent" | ||
| "401": | ||
| $ref: "#/components/responses/Unauthorized" | ||
| "404": | ||
| $ref: "#/components/responses/NotFound" | ||
| default: | ||
| $ref: "#/components/responses/Unexpected" | ||
| tags: | ||
| - Application Endpoint Registration | ||
| summary: Update a application Endpoint | ||
| description: Update registered application Endpoint information. | ||
|
There was a problem hiding this comment. Please clarify if the update completely replaces the existing array or does something else like appending to it. There was a problem hiding this comment. Moved the summary and the description to the top of the Schema. |
||
| delete: | ||
| operationId: deregister-application-endpoint | ||
| responses: | ||
| "204": | ||
| $ref: "#/components/responses/NoContent" | ||
| "400": | ||
| $ref: "#/components/responses/BadRequest" | ||
| "401": | ||
| $ref: "#/components/responses/Unauthorized" | ||
| "404": | ||
| $ref: "#/components/responses/NotFound" | ||
| default: | ||
| $ref: "#/components/responses/Unexpected" | ||
| tags: | ||
| - Application Endpoint Registration | ||
| summary: Deregister an application's application Endpoint | ||
| description: Deregister an application's application | ||
| Endpoint from the edge cloud zone. | ||
| components: | ||
| securitySchemes: | ||
| openId: | ||
| description: OpenID Provider Configuration Information | ||
| type: openIdConnect | ||
| openIdConnectUrl: https://example.com/.well-known/openid-configuration | ||
| headers: | ||
| x-correlator: | ||
| description: Correlation id for the different services | ||
| schema: | ||
| type: string | ||
|
|
||
| schemas: | ||
| ApplicationInstance: | ||
| description: Application instance represented | ||
| by application Endpoint definition | ||
| type: object | ||
|
There was a problem hiding this comment. I would suggest adding a There was a problem hiding this comment. Added "Required" section to the schema. |
||
| properties: | ||
| applicationEndpointsId: | ||
| $ref: "#/components/schemas/TypesApplicationEndpointsId" | ||
| applicationEndpoint: | ||
| $ref: "#/components/schemas/ResourcesapplicationEndpoint" | ||
| applicationServerProviderName: | ||
| type: string | ||
| description: Unique ID representing the Edge | ||
| Application Provider | ||
| applicationId: | ||
| type: string | ||
| description: Unique ID representing the Edge Application | ||
|
There was a problem hiding this comment. Is this really the applicationId or is it the appInstanceId? In the EAM API, the appId refers to definition of an App, like a helm chart, while the appInstanceId refers to an actually deployed instance of the helm chart. I ask because this object is called |
||
| applicationDescription: | ||
| type: string | ||
| description: Description of the application Endpoint | ||
| additionalProperties: false | ||
| applicationProfileId: | ||
| $ref: "#/components/schemas/TypesApplicationProfileId" | ||
| edgeCloudZoneId: | ||
| $ref: "#/components/schemas/EdgeCloudZoneId" | ||
| edgeCloudZoneName: | ||
| $ref: "#/components/schemas/EdgeCloudZoneName" | ||
| edgeCloudProvider: | ||
| $ref: "#/components/schemas/EdgeCloudProvider" | ||
| edgeCloudRegionId: | ||
| $ref: "#/components/schemas/EdgeCloudRegionName" | ||
|
Comment on lines
+354
to
+361
There was a problem hiding this comment. I have a question on the intent here. First, are these edgeCloudZone-related fields specified during the POST /application-endpoints API? If they are specified, is it expected that the Operator Platform handling the API call will verify that it has the specified Zone in it's list of zones (i.e., if I specify a random string for the Zone ID, it will reject it)? Or does it treat them as just a reference to some external Zone that it doesn't know about, so I could just put in anything there and I will just get it back out during the "find" API call? |
||
| ResourcesapplicationEndpoint: | ||
| type: object | ||
|
There was a problem hiding this comment. Should we assume that an application can expose only one endpoint or there could be more than one for different purposes? If there can be more than one which only application provider knows then this parameter should allow the multiplicity by having it as an array of objects. Also in that case with each endpoint there should be a discriminator field to allow client applications to know the purpose of a specific endpoint. There was a problem hiding this comment. Although the top level object is an array but then if application has multiple endpoints some of the information will be repeated that many times as they will be common to an application. There was a problem hiding this comment. I also had the same question about repetitive data in the array. For example, is it expected that applicationId is the same for each ApplicationInstance in the array? If any field must be the same for each item in the array, it should be factored out into a single field in a parent object that encapsulates the endpoints array. If every field in the array can be different, then what is the intent of assigning a single applicationEndpointsId to the entire array? |
||
| description: applicationEndpoint//added desc | ||
| 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 | ||
| ipv6Address: | ||
| type: string | ||
| description: IPv6 Address of application Endpoint if available | ||
| format: ipv6 | ||
| port: | ||
| type: integer | ||
| description: | | ||
| Port information of application Endpoint | ||
| if IPv4 or IPv6 is mentioned | ||
| 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 | ||
| TypesApplicationEndpointsId: | ||
|
There was a problem hiding this comment. I would suggest renaming |
||
| description: | | ||
| A system-defined string identifier representing | ||
| one or more registered Application Endpoints. | ||
| type: string | ||
| format: uuid | ||
| readOnly: true | ||
| additionalProperties: false | ||
| TypesApplicationProfileId: | ||
|
There was a problem hiding this comment. I would suggest renaming There was a problem hiding this comment. Modified "TypesApplicationProfileId" to "ApplicationProfileId" |
||
| description: | | ||
| Unique identifier for a Application Profile | ||
| type: string | ||
| readOnly: false | ||
| additionalProperties: false | ||
| TypesError: | ||
| type: object | ||
| description: types Error//added desc | ||
| properties: | ||
| code: | ||
| type: string | ||
| description: code //added desc | ||
| message: | ||
| type: string | ||
| description: message //added desc | ||
| ErrorInfo: | ||
| type: object | ||
| description: Error information | ||
| 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: | ||
| NoContent: | ||
| description: HTTP 204 No Content | ||
| BadRequest: | ||
| description: HTTP 400 Bad Request | ||
| content: | ||
| application/json: | ||
| schema: | ||
| $ref: "#/components/schemas/TypesError" | ||
| NotFound: | ||
| description: HTTP 404 The specified resource was not found | ||
| content: | ||
| application/json: | ||
| schema: | ||
| $ref: "#/components/schemas/TypesError" | ||
| Unauthorized: | ||
| description: HTTP 401 Unauthorized | ||
| content: | ||
| application/json: | ||
| schema: | ||
| $ref: "#/components/schemas/TypesError" | ||
| Unexpected: | ||
| description: HTTP 500 Internal Server Error | ||
| content: | ||
| application/json: | ||
| schema: | ||
| $ref: "#/components/schemas/TypesError" | ||
| Generic400: | ||
| description: Invalid argument | ||
| content: | ||
| application/json: | ||
| schema: | ||
| $ref: "#/components/schemas/ErrorInfo" | ||
| example: | ||
| status: 400 | ||
| code: INVALID_ARGUMENT | ||
| message: "Invalid argument" | ||
|
|
||
| Generic401: | ||
| description: Unauthenticated | ||
| content: | ||
| application/json: | ||
| schema: | ||
| $ref: "#/components/schemas/ErrorInfo" | ||
| example: | ||
| status: 401 | ||
| code: UNAUTHENTICATED | ||
| message: "Authorization failed: ..." | ||
|
|
||
| Generic403: | ||
| description: Permission denied | ||
| content: | ||
| application/json: | ||
| schema: | ||
| $ref: "#/components/schemas/ErrorInfo" | ||
| example: | ||
| status: 403 | ||
| code: PERMISSION_DENIED | ||
| message: "Operation not allowed: ..." | ||
|
|
||
| Generic404: | ||
| description: Not found | ||
| content: | ||
| application/json: | ||
| schema: | ||
| $ref: "#/components/schemas/ErrorInfo" | ||
| example: | ||
| status: 404 | ||
| code: NOT_FOUND | ||
| message: "The specified resource is not found" | ||
|
|
||
| Generic409: | ||
| description: Conflict | ||
| content: | ||
| application/json: | ||
| schema: | ||
| $ref: "#/components/schemas/ErrorInfo" | ||
| example: | ||
| status: 409 | ||
| code: Conflict | ||
| message: "There is conflict in the request" | ||
|
|
||
| Generic500: | ||
| description: Internal server error | ||
| content: | ||
| application/json: | ||
| schema: | ||
| $ref: "#/components/schemas/ErrorInfo" | ||
| example: | ||
| status: 500 | ||
| code: INTERNAL | ||
| message: "Internal server error" | ||
|
|
||
| Generic503: | ||
| description: application unavailable | ||
| content: | ||
| application/json: | ||
| schema: | ||
| $ref: "#/components/schemas/ErrorInfo" | ||
| example: | ||
| status: 503 | ||
| code: UNAVAILABLE | ||
| message: "application unavailable" | ||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Should we have a definition for "Application Endpoints" to make it more explicit?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I also think that these Application Endpoints are not generic and they corresponds to the application instances running on edge cloud zones in probably distributed manner. So should we qualify the Application Endpoints in some way to indicate developers about the expectations from these endpoints i.e. edge instances?