diff --git a/documentation/API proposals/APIproposal_SessionInsights_CableLabs.md b/documentation/API proposals/APIproposal_SessionInsights_CableLabs.md index 4afddab..534f638 100644 --- a/documentation/API proposals/APIproposal_SessionInsights_CableLabs.md +++ b/documentation/API proposals/APIproposal_SessionInsights_CableLabs.md @@ -1,16 +1,16 @@ -| **Field** | **Description** | -| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| API family name | Session Insights - original proposal was 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. | -| | **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
- [yaml OpenAPI Specification](../SupportingDocuments/sessioninsights-openapi.yaml)
- [yaml - Swagger Editor](https://editor.swagger.io/?url=https://raw.githubusercontent.com/cablelabs/APIBacklog/benhepworth-patch-2/documentation/SupportingDocuments/sessioninsights-openapi.yaml)
- [slides](../SupportingDocuments/session-insights-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/sessioninsights-openapi.yaml b/documentation/SupportingDocuments/sessioninsights-openapi.yaml deleted file mode 100644 index f6020ac..0000000 --- a/documentation/SupportingDocuments/sessioninsights-openapi.yaml +++ /dev/null @@ -1,601 +0,0 @@ -openapi: 3.0.3 -info: - title: Session Insights (SI) API - version: 0.0.1 -paths: - /sessions: - post: - tags: - - SI sessions - summary: Creates a new session - description: Create SI 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 Session Insights server will call this endpoint whenever any network related event occurs. - Currently only SI_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" - - /metrics/{sessionId}: - post: - tags: - - SI 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: - - SI sessions - summary: Get SI session information - description: Querying for SI 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" - - delete: - tags: - - SI sessions - summary: Delete a SI session - description: Free resources related to SI 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" - -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 - SIStatus: - $ref: " #/components/schemas/SIStatus" - messages: - type: array - items: - $ref: " #/components/schemas/Message" - creationInfo: - $ref: " #/components/schemas/CreateSession" - required: - - id - - startedAt - - expiresAt - - SIStatus - - 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 `SI_STATUS_CHANGED` event with - - `SIStatus` 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/SINetworkRequirements" - 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 - - SINetworkRequirements: - 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. - - SIResult: - 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 - - SIStatus: - description: | - The current status of the requested SI session. The status can be one of the following: - * `REQUESTED` - SI has been requested by creating a session - * `AVAILABLE` - The requested SI has been provided by the network - * `UNAVAILABLE` - The requested SI 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/SIStatusChangedEvent" - discriminator: - propertyName: eventType - mapping: - SI_STATUS_CHANGED: " #/components/schemas/SIStatusChangedEvent" - - EventId: - type: string - format: uuid - example: 5698d710-9b1b-4695-a958-7b228f08128c - description: Unique identifier of the event - - EventType: - type: string - enum: - - SI_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" - - SIStatusChangedEvent: - allOf: - - $ref: " #/components/schemas/EventBase" - - type: object - description: | - Event notifying that there was a change of the SI status of a requested or previously available session. - Applicable values for `SIStatus` in the event are: - - `AVAILABLE` - Requested SI session is already available - - `UNAVAILABLE` - A requested or previously available SI 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 - - SIStatus - properties: - sessionId: - $ref: " #/components/schemas/SessionId" - SIStatus: - $ref: " #/components/schemas/SIStatus" - statusInfo: - $ref: " #/components/schemas/StatusInfo" - required: - - eventDetail - - StatusInfo: - description: | - Reason for the new `SIStatus`. Currently `statusInfo` is only applicable when `SIStatus` 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"