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,372 @@ | ||
| 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 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 instance of the application. Addtionally the information can be used to also monitor the different instance to take decisions from a lifecycle mangement 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 application. | ||
|
|
||
| paths: | ||
| /application-endpoints: | ||
| 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. There was a problem hiding this comment. Added relevant status codes for all the APIs |
||
| 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 There was a problem hiding this comment. Agreed. "applicationId" is not referenced. Removed the parameter There was a problem hiding this comment. I believe this point needs more discussion. we need provide developers will more clarity and details on how these different APIs in edge cloud work togethers. EAM used for orchestrating the individual instances of the application. Application end point registration is a mechanism for creating a database of records for all the active and available application instances and the same information will be using in traffic influence and application end point discovery to identify the specific application instance. I think we need to take a closer look at how and where we are using the terms appId and appInstanceId There was a problem hiding this comment. Totally agree with you @maheshc01 , we should be careful and be clear how all this parameters are using along the different APIs. |
||
| 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? There was a problem hiding this comment. Yes, the edgeCloudZone-related fields are to be specified during the POST call. And it is expected that the Operator platform should verify whether its a valid cloud zone or not before the "ApplicationEndpointsId" gets created |
||
| 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? There was a problem hiding this comment. In this initial version, the API handles where an application has a single purpose but distributed across various edge locations so each application instance at a given edge location has an endpoint to register. There was a problem hiding this comment. The title "title: Application Endpoints Registration" has plural "Endpoints" as the keyword and based on the current form with single endpoint we may change it to singular form as endpoint or if we want to handle endpoints with different purposes in this release only then we need to provide option for multiple endpoint i.e. array in my view. There was a problem hiding this comment. "Application Endpoints" and its type "array" is still valid in this initial version because the same application can be deployed across multiple edge locations. There was a problem hiding this comment. So does this mean ResourcesapplicationEndpoint should be converted to an array in some way? Is that the right interpretation of your comment? There was a problem hiding this comment. I think this object is part of ApplicationEndpoints in the form of array. In that case my previous comment will become invalid. |
||
| 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.
I would have expected there to also be a
getmethod for/application-endpoints, to be able to list all of the registeredapplicationEndpointsId. Otherwise the client needs to maintain a database of the registeredapplicationEndpointsIdto be able to update/delete them later.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.
Agreed. Added GetAll API which lists all the registered applications.