diff --git a/documentation/API proposals/APIproposal_QualityByDesign_CableLabs.md b/documentation/API proposals/APIproposal_SessionInsights_CableLabs.md similarity index 71% rename from documentation/API proposals/APIproposal_QualityByDesign_CableLabs.md rename to documentation/API proposals/APIproposal_SessionInsights_CableLabs.md index c1c2a2c..534f638 100644 --- a/documentation/API proposals/APIproposal_QualityByDesign_CableLabs.md +++ b/documentation/API proposals/APIproposal_SessionInsights_CableLabs.md @@ -1,16 +1,16 @@ -| **Field** | **Description** | -| ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| API family name | Quality by Design (QbD) | -| API family owner | CableLabs | -| API summary | API allowing applications to:
- report application KPIs to network operator
- receive QbD score
- receive root cause analysis and recommended corrective actions
- request service improvements | -| | **API Scope**
This API would be part of the Connectivity Insights API Family. The QbD API allows an application developer to create a session with a network operator. The application can then share Key Performance Indicators (KPIs) such as:
- latency
- jitter
- packet loss
- bitrate
The network operator can monitors these KPIs and determine a QbD score. These KPIs are aligned with the attributes in the Connectivity Insights [application-profile](https://github.com/camaraproject/ConnectivityInsights/blob/main/code/API_definitions/application-profiles.yaml) to maintain consistency across CAMARA. If the score ever drop below certain thresholds, an event can be triggered. The network operator can then determine root cause and suggest corrective actions either to the application or to the network. | -| | **Use Case Example 1 - Wi-Fi Congestion**
Wi-Fi congestion at a [`Service Site`](https://github.com/camaraproject/NetworkAccessManagement/blob/1c804a5159f67370f005dbf0cc82e5c7e72725f0/code/API_definitions/network_access_management.yaml#L40) is affecting video conferencing performance, reflecting lower QbD scores and poor video quality | -| | **Use Case Example 2 - Network Impairments**
Issues in the operator's network can lead to degradation in latency, jitter, packet loss, and bitrate, reflecting lower QbD scores and poor video quality. | -| | **Sample Recommendations**
- create a HomeDeviceQoD session for WMM enablement
- application configuration updates
- request service improvements | -| Technical viability | Application developers can use this API to interact with the network. It assumes the network operator exposing this API has a backend to receive KPIs, analyze them, and produce a QbD score. Based on minimum quality thresholds for the application category, the network operator can provide proactive recommendations. The application could also use the CAMARA NetworkAccessManagement for remote control of a [`Device`](https://github.com/camaraproject/NetworkAccessManagement/blob/1c804a5159f67370f005dbf0cc82e5c7e72725f0/code/API_definitions/network_access_management.yaml#L34) at a [`Service Site`](https://github.com/camaraproject/NetworkAccessManagement/blob/1c804a5159f67370f005dbf0cc82e5c7e72725f0/code/API_definitions/network_access_management.yaml#L40) if necessary. | -| Commercial viability | Reference implementation developed by CableLabs with a sample video conferencing app using the API is being evaluated with network operators. | -| YAML code available? | YES
- [yaml OpenAPI Specification](../SupportingDocuments/qbd-openapi.yaml)
- [yaml - Swagger Editor](https://editor.swagger.io/?url=https://raw.githubusercontent.com/cablelabs/APIBacklog/benhepworth-patch-1/documentation/SupportingDocuments/qbd-openapi.yaml)
- [slides](../SupportingDocuments/quality-by-design-api.pdf) | -| Validated in lab/productive environments? | YES - app using APIs validated in CableLabs lab with potential field trials coming soon with network operators. | -| Validated with real customers? | NO - in progress with multiple application developers | -| Validated with operators? | YES | -| Supporters in API Backlog Working Group | Charter, Liberty Global, Vodafone | +| **Field** | **Description** | +| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| API family name | Session Insights - original proposal was named Quality by Design (QbD) | +| API family owner | CableLabs | +| API summary | API allowing applications to:
- report application KPIs to network operator
- receive Session Insights score
- receive root cause analysis and recommended corrective actions
- request service improvements | +| | **API Scope**
This API would be part of the Connectivity Insights API Family. The Session Insights API allows an application developer to create a session with a network operator. The application can then share Key Performance Indicators (KPIs) such as:
- latency
- jitter
- packet loss
- bitrate
The network operator can monitors these KPIs and determine a Session Insights score. These KPIs are aligned with the attributes in the Connectivity Insights [application-profile](https://github.com/camaraproject/ConnectivityInsights/blob/main/code/API_definitions/application-profiles.yaml) to maintain consistency across CAMARA. If the score ever drop below certain thresholds, an event can be triggered. The network operator can then determine root cause and suggest corrective actions either to the application or to the network.

Link to [proposal slides](../SupportingDocuments/session-insights-api.pdf). | +| | **Use Case Example 1 - Wi-Fi Congestion**
Wi-Fi congestion at a [`Service Site`](https://github.com/camaraproject/NetworkAccessManagement/blob/1c804a5159f67370f005dbf0cc82e5c7e72725f0/code/API_definitions/network_access_management.yaml#L40) is affecting video conferencing performance, reflecting lower Session Insights scores and poor video quality | +| | **Use Case Example 2 - Network Impairments**
Issues in the operator's network can lead to degradation in latency, jitter, packet loss, and bitrate, reflecting lower Session Insights scores and poor video quality. | +| | **Sample Recommendations**
- create a HomeDeviceQoD session for WMM enablement
- application configuration updates
- request service improvements | +| Technical viability | Application developers can use this API to interact with the network. It assumes the network operator exposing this API has a backend to receive KPIs, analyze them, and produce a Session Insights score. Based on minimum quality thresholds for the application category, the network operator can provide proactive recommendations. The application could also use the CAMARA NetworkAccessManagement for remote control of a [`Device`](https://github.com/camaraproject/NetworkAccessManagement/blob/1c804a5159f67370f005dbf0cc82e5c7e72725f0/code/API_definitions/network_access_management.yaml#L34) at a [`Service Site`](https://github.com/camaraproject/NetworkAccessManagement/blob/1c804a5159f67370f005dbf0cc82e5c7e72725f0/code/API_definitions/network_access_management.yaml#L40) if necessary. | +| Commercial viability | Reference implementation developed by CableLabs with a sample video conferencing app using the API is being evaluated with network operators. | +| YAML code available? | YES | +| Validated in lab/productive environments? | YES - app using APIs validated in CableLabs lab with potential field trials coming soon with network operators. | +| Validated with real customers? | NO - in progress with multiple application developers | +| Validated with operators? | YES | +| Supporters in API Backlog Working Group | Charter, Liberty Global, Vodafone | diff --git a/documentation/SupportingDocuments/qbd-openapi.yaml b/documentation/SupportingDocuments/qbd-openapi.yaml deleted file mode 100644 index 6c7333c..0000000 --- a/documentation/SupportingDocuments/qbd-openapi.yaml +++ /dev/null @@ -1,624 +0,0 @@ -openapi: 3.0.3 -info: - title: Quality by Design (QbD) API - version: 0.0.1 -# security: -# - oAuth2ClientCredentials: [] -# servers: -# - url: "{apiRoot}/{basePath}" -# variables: -# apiRoot: -# default: http://localhost:5000 -# description: API root -# basePath: -# default: qbd/v0 -# description: Base path for the QbD API -paths: - /sessions: - post: - tags: - - QbD sessions - summary: Creates a new session - description: Create QbD Session to query network quality information - operationId: createSession - x-router-controller: SessionController - requestBody: - description: Parameters to create a new session - content: - application/json: - schema: - $ref: "#/components/schemas/CreateSession" - required: true - callbacks: - notifications: - "{$request.body#/webhook/notificationUrl}": - post: - tags: - - Session notifications callback - summary: "Session notifications callback" - description: | - Important: this endpoint is to be implemented by the API consumer. - The QbD server will call this endpoint whenever any network related event occurs. - Currently only QBD_STATUS_CHANGED event is defined. - operationId: postNotification - requestBody: - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/EventNotification" - responses: - "204": - description: Successful notification - "400": - $ref: "#/components/responses/Generic400" - "401": - $ref: "#/components/responses/Generic401" - "403": - $ref: "#/components/responses/Generic403" - "500": - $ref: "#/components/responses/Generic500" - "503": - $ref: "#/components/responses/Generic503" - # security: - # - {} - # - notificationsBearerAuth: [] - responses: - "201": - description: Session created - content: - application/json: - schema: - $ref: "#/components/schemas/SessionInfo" - "400": - description: Invalid input for createSession operation - content: - application/json: - schema: - $ref: "#/components/schemas/ErrorInfo" - examples: - Generic400: - summary: Some parameter combinations or parameter values provided are not schema compliant - value: - status: 400 - code: INVALID_INPUT - message: "Schema validation failed at ..." - "401": - $ref: "#/components/responses/Generic401" - "403": - $ref: "#/components/responses/Generic403" - "409": - description: Conflict - content: - application/json: - schema: - $ref: "#/components/schemas/ErrorInfo" - example: - status: 409 - code: CONFLICT - message: "Another session is created for the same UE" - "500": - description: Server error - content: - application/json: - schema: - $ref: "#/components/schemas/ErrorInfo" - example: - status: 500 - code: INTERNAL - message: "Session could not be created" - "503": - $ref: "#/components/responses/Generic503" - # security: - # - oAuth2ClientCredentials: [] - # - threeLegged: - # - "qbd-sessions-write" - - /metrics/{sessionId}: - post: - tags: - - QbD sessions - summary: Post metrics data for a session - parameters: - - in: path - name: sessionId - description: Session ID that was obtained from the createSession operation - required: true - schema: - $ref: "#/components/schemas/SessionId" - requestBody: - required: true - content: - application/json: - schema: - type: object - properties: - packet_loss: - type: integer - description: Packet loss value - latency: - type: integer - description: Latency value - jitter: - type: integer - description: Jitter value - bitrate: - type: integer - description: Bitrate value - required: - - packet_loss - - latency - - jitter - - bitrate - responses: - "200": - description: Metrics data successfully posted - content: - application/json: - schema: - type: object - properties: - message: - type: string - example: Metrics data successfully posted - "400": - description: Bad request - content: - application/json: - schema: - type: object - properties: - error: - type: string - example: Invalid request data - - /sessions/{sessionId}: - get: - tags: - - QbD sessions - summary: Get QbD session information - description: Querying for QbD session resource information details - operationId: getSession - x-router-controller: SessionController - parameters: - - name: sessionId - in: path - description: Session ID that was obtained from the createSession operation - required: true - schema: - $ref: "#/components/schemas/SessionId" - responses: - "200": - description: Contains information about active session - content: - application/json: - schema: - $ref: "#/components/schemas/SessionInfo" - "401": - $ref: "#/components/responses/Generic401" - "403": - $ref: "#/components/responses/Generic403" - "404": - $ref: "#/components/responses/SessionNotFound404" - "500": - $ref: "#/components/responses/Generic500" - "503": - $ref: "#/components/responses/Generic503" - # security: - # - oAuth2ClientCredentials: [] - # - threeLegged: - # - "qbd-sessions-read" - - delete: - tags: - - QbD sessions - summary: Delete a QbD session - description: Free resources related to QbD session - operationId: deleteSession - x-router-controller: SessionController - parameters: - - name: sessionId - in: path - description: Session ID that was obtained from the createSession operation - required: true - schema: - $ref: "#/components/schemas/SessionId" - responses: - "204": - description: Session deleted - "401": - $ref: "#/components/responses/Generic401" - "403": - $ref: "#/components/responses/Generic403" - "404": - $ref: "#/components/responses/SessionNotFound404" - "500": - $ref: "#/components/responses/Generic500" - "503": - $ref: "#/components/responses/Generic503" - # security: - # - oAuth2ClientCredentials: [] - # - threeLegged: - # - "qbd-sessions-delete" - -components: - schemas: - SessionId: - type: string - format: uuid - description: Session ID in UUID format - - SessionInfo: - description: Session related information. - type: object - properties: - id: - $ref: "#/components/schemas/SessionId" - startedAt: - type: integer - example: 1639479600 - description: Timestamp of session start in seconds since unix epoch - format: int64 - expiresAt: - type: integer - example: 1639566000 - description: Timestamp of session expiration if the session was not deleted, in seconds since unix epoch - format: int64 - qbdStatus: - $ref: "#/components/schemas/QbdStatus" - messages: - type: array - items: - $ref: "#/components/schemas/Message" - creationInfo: - $ref: "#/components/schemas/CreateSession" - required: - - id - - startedAt - - expiresAt - - qbdStatus - - CreateSession: - description: Attributes required to create a session - type: object - properties: - duration: - description: | - Session duration in seconds. Maximal value of 24 hours is used if not set. - After session is expired the, client will receive a `QBD_STATUS_CHANGED` event with - - `qbdStatus` as `UNAVAILABLE`, and, - - `statusInfo` as `DURATION_EXPIRED`. - See notification callback. - type: integer - format: int32 - minimum: 1 - maximum: 86400 - default: 86400 - example: 86400 - applicationServer: - $ref: "#/components/schemas/ApplicationServer" - networkRequirements: - $ref: "#/components/schemas/QbDNetworkRequirements" - webhook: - type: object - required: - - notificationUrl - properties: - notificationUrl: - type: string - format: uri - example: "https://application-server.com" - description: Allows asynchronous delivery of session related events - notificationAuthToken: - type: string - minLength: 20 - maxLength: 256 - example: "c8974e592c2fa383d4a3960714" - description: Authentication token for callback API - required: - - duration - - applicationServer - - ApplicationServer: - description: | - A server hosting backend applications to deliver some business logic to clients. - - The developer can choose to provide the below specified device identifiers: - - * `ipv4Address` - * `ipv6Address` - type: object - properties: - ipv4Address: - $ref: "#/components/schemas/Ipv4Address" - ipv6Address: - $ref: "#/components/schemas/Ipv6Address" - minProperties: 1 - - Ipv4Address: - type: string - pattern: '^([01]?\d\d?|2[0-4]\d|25[0-5])(?:\.(?:[01]?\d\d?|2[0-4]\d|25[0-5])){3}(\/([0-9]|[1-2][0-9]|3[0-2]))?$' - example: "192.168.0.1/24" - description: | - IPv4 address may be specified in form
as: - - address - an IPv4 number in dotted-quad form 1.2.3.4. Only this exact IP number will match the flow control rule. - - address/mask - an IP number as above with a mask width of the form 1.2.3.4/24. - In this case, all IP numbers from 1.2.3.0 to 1.2.3.255 will match. The bit width MUST be valid for the IP version. - - Ipv6Address: - type: string - example: "2001:db8:85a3:8d3:1319:8a2e:370:7344" - description: | - IPv6 address, following IETF 5952 format, may be specified in form
as: - - address - The /128 subnet is optional for single addresses: - - 2001:db8:85a3:8d3:1319:8a2e:370:7344 - - 2001:db8:85a3:8d3:1319:8a2e:370:7344/128 - - address/mask - an IP v6 number with a mask: - - 2001:db8:85a3:8d3::0/64 - - 2001:db8:85a3:8d3::/64 - - QbDNetworkRequirements: - type: object - required: - - latenciesByPercentile - properties: - latenciesByPercentile: - $ref: "#/components/schemas/LatenciesByPercentileRequirement" - packetLoss: - $ref: "#/components/schemas/PacketLossRequirement" - - LatenciesByPercentileRequirement: - type: array - description: An array of pairs (percentile, (latencyPerfectOutcome, latencyUselessOutcome)). - minItems: 1 - maxItems: 100 - uniqueItems: true - items: - type: object - required: - - percentile - - latencies - properties: - percentile: - type: integer - minimum: 1 - maximum: 100 - latencies: - type: object - description: Latency values measured in milliseconds (ms) for perfect and useless application outcome at a given percentile. - properties: - latencyPerfectOutcome: - type: integer - latencyUselessOutcome: - type: integer - required: - - latencyPerfectOutcome - - latencyUselessOutcome - - PacketLossRequirement: - type: object - required: - - timeSpan - properties: - lostPacketsPerfectOutcome: - type: integer - lostPacketsUselessOutcome: - type: integer - timeSpan: - type: integer - description: Time span in seconds to consider for QoO analysis based on packet loss. - - QbdResult: - description: Resulting Quality by Design data for a session - type: object - properties: - score: - type: integer - minimum: 1 - maximum: 100 - required: - - score - - Message: - type: object - properties: - severity: - description: Message severity - type: string - enum: ["INFO", "WARNING"] - description: - description: Detailed message text - type: string - required: - - severity - - description - - QbdStatus: - description: | - The current status of the requested QbD session. The status can be one of the following: - * `REQUESTED` - QbD has been requested by creating a session - * `AVAILABLE` - The requested QbD has been provided by the network - * `UNAVAILABLE` - The requested QbD cannot be provided by the network due to some reason - type: string - enum: - - REQUESTED - - AVAILABLE - - UNAVAILABLE - - EventNotification: - type: object - required: - - event - properties: - event: - $ref: "#/components/schemas/Event" - - Event: - anyOf: - - $ref: "#/components/schemas/QbdStatusChangedEvent" - discriminator: - propertyName: eventType - mapping: - QBD_STATUS_CHANGED: "#/components/schemas/QbdStatusChangedEvent" - - EventId: - type: string - format: uuid - example: 5698d710-9b1b-4695-a958-7b228f08128c - description: Unique identifier of the event - - EventType: - type: string - enum: - - QBD_STATUS_CHANGED - description: Type of the event - - EventTime: - type: string - format: date-time - example: 2023-05-30T10:18:28Z - description: Date time when the event occurred - - EventBase: - type: object - required: - - eventType - - eventTime - properties: - eventid: - $ref: "#/components/schemas/EventId" - eventType: - $ref: "#/components/schemas/EventType" - eventTime: - $ref: "#/components/schemas/EventTime" - - QbdStatusChangedEvent: - allOf: - - $ref: "#/components/schemas/EventBase" - - type: object - description: | - Event notifying that there was a change of the QbD status of a requested or previously available session. - Applicable values for `qbdStatus` in the event are: - - `AVAILABLE` - Requested QbD session is already available - - `UNAVAILABLE` - A requested or previously available QbD session is currently unavailable. `statusInfo` may provide additional information about the reason for the unavailability. - properties: - eventDetail: - type: object - description: Event details depending on the event type - required: - - sessionId - - qbdStatus - properties: - sessionId: - $ref: "#/components/schemas/SessionId" - qbdStatus: - $ref: "#/components/schemas/QbdStatus" - statusInfo: - $ref: "#/components/schemas/StatusInfo" - required: - - eventDetail - - StatusInfo: - description: | - Reason for the new `qbdStatus`. Currently `statusInfo` is only applicable when `qbdStatus` is 'UNAVAILABLE'. - * `DURATION_EXPIRED` - Session terminated due to requested duration expired - * `NETWORK_TERMINATED` - Network terminated the session before the requested duration expired - type: string - enum: - - DURATION_EXPIRED - - NETWORK_TERMINATED - - ErrorInfo: - type: object - 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 - required: - - status - - code - - message - - responses: - Generic400: - description: Invalid input - content: - application/json: - schema: - $ref: "#/components/schemas/ErrorInfo" - example: - status: 400 - code: INVALID_ARGUMENT - message: "Schema validation failed at ..." - - Generic401: - description: Unauthorized - content: - application/json: - schema: - $ref: "#/components/schemas/ErrorInfo" - example: - status: 401 - code: UNAUTHENTICATED - message: "Authorization failed: ..." - - Generic403: - description: Forbidden - content: - application/json: - schema: - $ref: "#/components/schemas/ErrorInfo" - example: - status: 403 - code: PERMISSION_DENIED - message: "Operation not allowed: ..." - - SessionNotFound404: - description: Session not found - content: - application/json: - schema: - $ref: "#/components/schemas/ErrorInfo" - example: - status: 404 - code: NOT_FOUND - message: "Session Id does not exist" - - Generic500: - description: Internal server error - content: - application/json: - schema: - $ref: "#/components/schemas/ErrorInfo" - example: - status: 500 - code: INTERNAL - message: "Internal server error: ..." - - Generic501: - description: Not Implemented - content: - application/json: - schema: - $ref: "#/components/schemas/ErrorInfo" - example: - status: 501 - code: NOT_IMPLEMENTED - message: "Service not implemented for the specified user device" - - Generic503: - description: Service unavailable - content: - application/json: - schema: - $ref: "#/components/schemas/ErrorInfo" - example: - status: 503 - code: UNAVAILABLE - message: "Service unavailable" diff --git a/documentation/SupportingDocuments/quality-by-design-api.pdf b/documentation/SupportingDocuments/quality-by-design-api.pdf deleted file mode 100755 index f11740d..0000000 Binary files a/documentation/SupportingDocuments/quality-by-design-api.pdf and /dev/null differ diff --git a/documentation/SupportingDocuments/quality-by-design-connectivity-insights.pdf b/documentation/SupportingDocuments/quality-by-design-connectivity-insights.pdf deleted file mode 100755 index e9ef468..0000000 Binary files a/documentation/SupportingDocuments/quality-by-design-connectivity-insights.pdf and /dev/null differ diff --git a/documentation/SupportingDocuments/session-insights-api.pdf b/documentation/SupportingDocuments/session-insights-api.pdf new file mode 100644 index 0000000..c15265e Binary files /dev/null and b/documentation/SupportingDocuments/session-insights-api.pdf differ