diff --git a/code/API_definitions/application-profiles.yaml b/code/API_definitions/application-profiles.yaml new file mode 100644 index 0000000000..2eca52bb86 --- /dev/null +++ b/code/API_definitions/application-profiles.yaml @@ -0,0 +1,419 @@ +--- +openapi: 3.0.3 +info: + title: Connectivity Insights API + version: "0.3.0-wip" + contact: + email: sp-coi@lists.camaraproject.org + license: + name: Apache 2.0 + url: https://www.apache.org/licenses/LICENSE-2.0.html + description: | + Application profiles allows application developers to share all the information about their application which would be relavant in network/CAMARA APIs related decision making. //todo +servers: + - url: "{apiRoot}/{basePath}" + variables: + apiRoot: + default: http://localhost:9091 + description: API root + basePath: + default: connectivity-insights/v0 + description: Base path for the Connectivity Insights API + +tags: + - name: Application Profiles + description: Operations to define, read and manage an application's thresholds for network quality (latency, jitter, loss, throughput) + +paths: + /application-profiles: + post: + security: + - openId: + - connectivity_insights:policy:write + tags: + - Application Profiles + summary: create a policy which represents an application's networking demands. + description: Define network monitoring intents for optimal end user application experience + operationId: createPolicy + requestBody: + description: List of user object + content: + "*/*": + schema: + $ref: "#/components/schemas/NetworkQualityThresholds" + required: true + responses: + "200": + description: good + content: + application/json: + schema: + $ref: "#/components/schemas/ApplicationProfileId" + "400": + $ref: "#/components/responses/Generic400" + "401": + $ref: "#/components/responses/Generic401" + "403": + $ref: "#/components/responses/Generic403" + "404": + $ref: "#/components/responses/Generic404" + "409": + $ref: "#/components/responses/Generic409" + "500": + $ref: "#/components/responses/Generic500" + "503": + $ref: "#/components/responses/Generic503" + + /application-profiles/{applicationProfileId}: + put: + security: + - openId: + - connectivity_insights:application_profile:write + tags: + - Application Profiles + description: Update the network quality thresholds for an application that ensure good end user experience + operationId: updateApplicationProfile + parameters: + - name: applicationProfileId + in: path + description: Identifier for the Aplpication Profile + required: true + style: simple + explode: false + schema: + type: string + format: uuid + requestBody: + description: Update the network quality thresholds that the application needs to deliver an acceptable user experience. + content: + "*/*": + schema: + $ref: "#/components/schemas/ApplicationProfile" + required: true + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/ApplicationProfile" + "400": + $ref: "#/components/responses/Generic400" + "401": + $ref: "#/components/responses/Generic401" + "403": + $ref: "#/components/responses/Generic403" + "404": + $ref: "#/components/responses/Generic404" + "409": + $ref: "#/components/responses/Generic409" + "500": + $ref: "#/components/responses/Generic500" + "503": + $ref: "#/components/responses/Generic503" + + get: + security: + - openId: + - connectivity_insights:application_profile:read + tags: + - Application Profiles + description: Read an Application Profile + operationId: readApplicationProfile + parameters: + - name: applicationProfileId + in: path + description: Identifier for the Application Profile + required: true + style: simple + explode: false + schema: + type: string + format: uuid + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/ApplicationProfile" + "400": + $ref: "#/components/responses/Generic400" + "401": + $ref: "#/components/responses/Generic401" + "403": + $ref: "#/components/responses/Generic403" + "404": + $ref: "#/components/responses/Generic404" + "409": + $ref: "#/components/responses/Generic409" + "500": + $ref: "#/components/responses/Generic500" + "503": + $ref: "#/components/responses/Generic503" + + delete: + security: + - openId: + - connectivity_insights:application_profile:write + tags: + - Application Profiles + description: delete + operationId: deleteApplicationProfile + parameters: + - name: applicationProfileId + in: path + description: subscription Id + required: true + style: simple + explode: false + schema: + type: string + format: uuid + responses: + "200": + description: policy has been deleted + "400": + $ref: "#/components/responses/Generic400" + "401": + $ref: "#/components/responses/Generic401" + "403": + $ref: "#/components/responses/Generic403" + "404": + $ref: "#/components/responses/Generic404" + "409": + $ref: "#/components/responses/Generic409" + "500": + $ref: "#/components/responses/Generic500" + "503": + $ref: "#/components/responses/Generic503" + +components: + securitySchemes: + openId: + type: openIdConnect + openIdConnectUrl: .well-known/openid-configuration + + schemas: + Duration: + type: object + properties: + value: + type: integer + example: 12 + format: int32 + minimum: 1 + unit: + allOf: + - $ref: "#/components/schemas/TimeUnitEnum" + - example: Minutes + + TimeUnitEnum: + type: string + enum: + - Days + - Hours + - Minutes + - Seconds + - Milliseconds + - Microseconds + - Nanoseconds + + Rate: + type: object + properties: + value: + type: integer + example: 10 + format: int32 + minimum: 0 + maximum: 1024 + unit: + $ref: "#/components/schemas/RateUnitEnum" + + RateUnitEnum: + type: string + enum: + - bps + - kbps + - Mbps + - Gbps + - Tbps + + packetDelayBudget: + description: | + The packet delay budget is the maximum allowable one-way latency between the customer's device + and the gateway from the operator's network to other networks. By limiting the delay, the network + can provide an acceptable level of performance for various services, such as voice calls, + video streaming, and data. + The end-to-end or round trip latency will be about two times this value plus the latency not controlled + by the operator + allOf: + - $ref: "#/components/schemas/Duration" + + packetErrorLossRate: + type: integer + description: | + The exponential power of the allowable error loss rate 10^(-N). + For instance 3 would be an error loss rate of 10 to the power of -3 (0.001) + + For 5G network the 3GPP specification TS 23.203 defines the packet error loss rate QCI attribute. It + describes the Quality of Service (QoS) Class Identifier (QCI) parameters used to + differentiate traffic classes in mobile networks, ensuring appropriate resource + allocation and performance for various services. + + The packet error loss rate is one of the QCI attributes, providing information on the + acceptable packet loss rate for a specific traffic class. This attribute helps maintain + the desired performance level for services like voice calls, video streaming, or data + transfers within the 3GPP mobile network. + format: int32 + minimum: 1 + maximum: 10 + example: 3 + + jitter: + description: | + The jitter requirement aims to limit the maximum variation in round-trip + packet delay for the 99th percentile of traffic, following ITU Y.1540 + standards. It considers only acknowledged packets in a session, which are + packets that receive a confirmation of receipt from the recipient (e.g., + using TCP). This requirement helps maintain consistent latency, essential + for real-time applications such as VoIP, video calls, and gaming. + allOf: + - $ref: "#/components/schemas/Duration" + + targetMinDownstreamRate: + description: | + This is the target minimum downstream rate. + allOf: + - $ref: "#/components/schemas/Rate" + + targetMinUpstreamRate: + description: | + This is the target minimum upstream rate. + allOf: + - $ref: "#/components/schemas/Rate" + + ApplicationProfile: + type: object + properties: + applicationProfileId: + type: string + format: uuid + networkQualityThresholds: + $ref: "#/components/schemas/NetworkQualityThresholds" + + NetworkQualityThresholds: + type: object + properties: + packetDelayBudget: + $ref: "#/components/schemas/packetDelayBudget" + targetMinDownstreamRate: + $ref: "#/components/schemas/targetMinDownstreamRate" + targetMinUpstreamRate: + $ref: "#/components/schemas/targetMinUpstreamRate" + packetlossErrorRate: + $ref: "#/components/schemas/packetErrorLossRate" + jitter: + $ref: "#/components/schemas/jitter" + + ApplicationProfileId: + description: Identifier for the Aplpication Profile + type: string + format: uuid + + 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: + 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: Service unavailable + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + example: + status: 503 + code: UNAVAILABLE + message: "Service unavailable" diff --git a/code/API_definitions/quality-on-demand.yaml b/code/API_definitions/quality-on-demand.yaml index 5363730a65..e6508855b6 100644 --- a/code/API_definitions/quality-on-demand.yaml +++ b/code/API_definitions/quality-on-demand.yaml @@ -496,6 +496,8 @@ components: - $ref: "#/components/schemas/PortsSpec" qosProfile: $ref: "#/components/schemas/QosProfileName" + applicationProfileId: + $ref: "#/components/schemas/ApplicationProfileId" webhook: description: Callback URL on which notifications about all status change events of the session (eg. session termination) can be received type: object @@ -646,6 +648,12 @@ components: format: string pattern: "^[a-zA-Z0-9_.-]+$" + ApplicationProfileId: + description: + Identifier for the Aplpication Profile which contains information with respect to what are the ideal network performance KPIs required for best end user experience. + type: string + format: uuid + CloudEvent: description: Event compliant with the CloudEvents specification required: