Add User Experience Insights API endpoints to Connectivity Insights project by cmhkknight · Pull Request #199 · camaraproject/ConnectivityInsights

cmhkknight · 2026-07-22T09:58:28Z

What type of PR is this?

Add one of the following kinds:

enhancement/feature

What this PR does / why we need it:

Add User Experience Insights API endpoints to Connectivity Insights project.
This PR introduces two new capabilities:

POST /user-experience-insights endpoint in connectivity-insights.yaml - Allows developers to query detailed application experience analysis data including QoE scores, resolution, stalling, latency, and bandwidth statistics for a given device.
Subscription support in connectivity-insights-subscriptions.yaml - Enables subscription-based notifications for user experience insights events with new event types and data models.
These enhancements address the need for multi-dimensional application real-use experience analysis as discussed in issue [Discussion] Defining Boundaries for User Experience Insights API: Focusing on Multi-Dimensional Application Real-Use Experience #185, allowing developers to make data-driven application strategy adjustments based on real-use network experience.

Which issue(s) this PR fixes:

Fixes #185

Special notes for reviewers:

This API definition is based on x-camara-commonalities: 0.6.0.

Next step is to update to x-camara-commonalities: 0.8.0.

Changelog input

 release-note

Additional documentation

This section can be blank.

docs

Added User Experience Insights section and related schemas for subscription details, including UserExperienceInsightsSubscriptionDetail and UserExperienceInsightsRecords.

Added user experience insights API details including request and response structures for application experience analysis.

XunliYang · 2026-07-28T02:24:04Z

Hi @maheshc01 @Kevsy @urvika-v , as discussed on #185 , @cmhkknight have added the new endpoint on POST /user-experience-insights and added user experience insights events on connectivity-insights-subscriptions. Please have a review when you have a moment!

Additionally, this PR is based on x-camara-commonalities v0.6.0. If possible, merging this prior to #198 would help avoid merge conflicts. We will then submit a follow-up PR to align with x-camara-commonalities v0.8.0.

benhepworth · 2026-07-29T15:34:55Z

as per 7/25 call: targeting for Sync 26 as part of RC2

- rename /user-experience-insights operationId to checkUserExperienceInsights and scope to connectivity-insights:user-experience-insights:check - add comprehensive user-experience-insights scenarios in connectivity-insights.feature (happy path and 400/401/403/404/422/429) - add user-experience subscription scenarios in connectivity-insights-subscriptions.feature and renumber scenarios sequentially (01-32)

XunliYang · 2026-08-28T10:03:29Z

Test cases have been added, and most validation hint issues have been resolved. The remaining 4 issues are all constraint-related for the city/district fields. Since these string fields do not require constraints, per CAMARA validation recommendations, no fixes are needed for them.

Kevsy · 2026-08-28T10:06:54Z

-            Maximum resolution in the experience analysis period.
+            Maximum resolution in the experience analysis period, expressed in
+            vertical pixels (e.g. 720, 1080, 2160).
        mostResolution:


Can I suggest to rename this to 'majorityResolution'? 'Most' is a synonym for 'maximum' so may cause confusion with 'maxResolution'.

Good point — 'majorityResolution' seems better. Renamed in both connectivity-insights.yaml and connectivity-insights-subscriptions.yaml.

Kevsy · 2026-08-28T10:39:20Z

      description: |
        QoS Class Identifier or 5G QoS Identifier.

    NetType:


Best to reuse the existing CAMARA definition for this from the DeviceStatus repository: https://github.com/camaraproject/DeviceStatus/blob/main/code/API_definitions/connected-network-type.yaml

Agreed. Updated the NetType enum to 2G / 3G / 4G / 5G / UNKNOWN, aligned with ConnectedNetworkType from the DeviceStatus repo.

Note: since there is no shared commonality module for this yet, the values are defined locally rather than cross-referencing the other repo.

Kevsy · 2026-08-28T10:43:29Z

+      pattern: '^[a-zA-Z0-9.-]+$'
      description: |
-        String representing a Data Network as defined in clause 9A of 3GPP TS 23.003.
+        String representing a Data Network as defined in clause 9A of 3GPP TS 23.003;


"String representing a Data Network" -> "String representing a Data Network Name"

Kevsy · 2026-08-28T10:45:21Z

+      pattern: '^\d+(\.\d+)? (bps|Kbps|Mbps|Gbps|Tbps)$'
      description: |
-        String representing a bit rate.
+        String representing a bit rate, formatted as a number followed by a


Best to reuse the existing 'Rate ' and 'RateUntiEnum' definitions from QoS Profiles

Done. Refactored BitRate from a string into an object { value: integer, unit: RateUnitEnum } and added a local RateUnitEnum (bps/kbps/Mbps/Gbps/Tbps), matching the QoS Profiles shape. Edited both files.

Kevsy · 2026-08-28T10:45:29Z


    ApplicationType:
-      description: Indicates the Application type. Negotiated by the carrier and application vendor and configured on the carrier network.
+      description: |


A few comments here:

'traffic class' is more accurate than 'application type', as 'type' can cover other application contexts (e.g. OS type, commercial model, genre etc.). But it's specifically the typical nature of the flow we are concerned with, so 'traffic class' is a good fit.

negotiation of values between API consumers and operators is against the CAMARA principle of reducing operator fragmentation. So a standard set of values makes sense.

Together, (1) and (2) suggests adopting an industry standard, e.g. 3GPP TS 23.107:

Traffic Class Typical Applications Key QoS Characteristic

Conversational Voice calls, video calls, telepresence Very low delay and jitter

Streaming Video/audio streaming Continuous media flow; some delay acceptable

Interactive Web browsing, database queries, online transactions Low response time important

Background Email, file transfer, backups, software downloads Delay insensitive; reliability more important

That really makes sense. I completely agree that adopting a standardized set of values is essential to prevent operator fragmentation per CAMARA principles. My original intent was to use developer-friendly application categories so that developers can choose specific application types to subscribe to experience insights for a given class of applications.

However, relying on 3GPP TS 23.107 Traffic Classes is too coarse-grained for Experience Insight subscriptions. To precisely subscribe to and evaluate insights for specific application behaviors, we need a finer-grained categorization.

Thus, I suggest using a developer-friendly, semantic categorization approach with pre-defined standardized enums for Application Type:

enum: - aigc # Generative AI services and interactive agent traffic - file_transfer # Bulk data upload/download, cloud storage sync, and backups - instant_messaging # Real-time text, voice messaging, and asynchronous chat - live_streaming # Uplink live broadcast publishing (Streamer / Uplink) - live_viewing # Downlink live stream viewing (Audience / Downlink) - meeting # Multi-party audio/video conferencing and screen sharing - mobile_gaming # Low-latency multiplayer online gaming and cloud gaming - short_video # Short-form video playback and feed consumption - vod_streaming # On-demand high-definition video streaming (VOD) - voip # Two-party voice and video telephony calls

Alternatively, should we align with the standard serviceClass enum in QoS Profiles to maintain consistency across CAMARA APIs?

Kevsy · 2026-08-28T10:56:36Z

KYC use 'region' instead of city, to cover users outside of cities. Can that be adopted?

Agreed. Align with KYC.

Kevsy

I've made some inline suggestions and comments, but the major required change is to remove the duplicate features in the tests.

XunliYang · 2026-08-31T07:15:56Z

I've made some inline suggestions and comments, but the major required change is to remove the duplicate features in the tests.

Thanks @Kevsy , I'm solving on these comments. Still I'm a bit confused about the duplicate features issue, do you mean that I can remove the similar test features and put two end point together? such as:

# 400 Error Scenarios

   @connectivity_insights_09_no_authorization_header
  Scenario: No Authorization header
    Given the header "Authorization" is removed
    And a valid network quality insight or user experience insight request body
    When the request "checkNetworkQuality" or "checkUserExperience" is sent
    Then the response code is 401
    And the response property "$.status" is 401
    And the response property "$.code" is "UNAUTHENTICATED"
    And the response property "$.message" contains a user friendly text

XunliYang

Left with two open items: applicationType definition and duplicate test features. Will update as soon as we reach a conclusion.

XunliYang · 2026-08-31T06:58:34Z

-            Maximum resolution in the experience analysis period.
+            Maximum resolution in the experience analysis period, expressed in
+            vertical pixels (e.g. 720, 1080, 2160).
        mostResolution:


Good point — 'majorityResolution' seems better. Renamed in both connectivity-insights.yaml and connectivity-insights-subscriptions.yaml.

XunliYang · 2026-08-31T07:01:21Z

Agreed. Align with KYC.

XunliYang · 2026-08-31T07:02:20Z

+      pattern: '^\d+(\.\d+)? (bps|Kbps|Mbps|Gbps|Tbps)$'
      description: |
-        String representing a bit rate.
+        String representing a bit rate, formatted as a number followed by a


Done. Refactored BitRate from a string into an object { value: integer, unit: RateUnitEnum } and added a local RateUnitEnum (bps/kbps/Mbps/Gbps/Tbps), matching the QoS Profiles shape. Edited both files.

XunliYang · 2026-08-31T07:03:20Z

+      pattern: '^[a-zA-Z0-9.-]+$'
      description: |
-        String representing a Data Network as defined in clause 9A of 3GPP TS 23.003.
+        String representing a Data Network as defined in clause 9A of 3GPP TS 23.003;


XunliYang · 2026-08-31T07:05:00Z

      description: |
        QoS Class Identifier or 5G QoS Identifier.

    NetType:


Agreed. Updated the NetType enum to 2G / 3G / 4G / 5G / UNKNOWN, aligned with ConnectedNetworkType from the DeviceStatus repo.

Note: since there is no shared commonality module for this yet, the values are defined locally rather than cross-referencing the other repo.

XunliYang · 2026-09-01T03:39:33Z


    ApplicationType:
-      description: Indicates the Application type. Negotiated by the carrier and application vendor and configured on the carrier network.
+      description: |


That really makes sense. I completely agree that adopting a standardized set of values is essential to prevent operator fragmentation per CAMARA principles. My original intent was to use developer-friendly application categories so that developers can choose specific application types to subscribe to experience insights for a given class of applications.

However, relying on 3GPP TS 23.107 Traffic Classes is too coarse-grained for Experience Insight subscriptions. To precisely subscribe to and evaluate insights for specific application behaviors, we need a finer-grained categorization.

Thus, I suggest using a developer-friendly, semantic categorization approach with pre-defined standardized enums for Application Type:

enum: - aigc # Generative AI services and interactive agent traffic - file_transfer # Bulk data upload/download, cloud storage sync, and backups - instant_messaging # Real-time text, voice messaging, and asynchronous chat - live_streaming # Uplink live broadcast publishing (Streamer / Uplink) - live_viewing # Downlink live stream viewing (Audience / Downlink) - meeting # Multi-party audio/video conferencing and screen sharing - mobile_gaming # Low-latency multiplayer online gaming and cloud gaming - short_video # Short-form video playback and feed consumption - vod_streaming # On-demand high-definition video streaming (VOD) - voip # Two-party voice and video telephony calls

Alternatively, should we align with the standard serviceClass enum in QoS Profiles to maintain consistency across CAMARA APIs?

- rename mostResolution to majorityResolution to avoid confusion with maxResolution - rename AreaData.city to region to cover users outside cities - align NetType enum with DeviceStatus ConnectedNetworkType (2G/3G/4G/5G/UNKNOWN) - refactor BitRate into object with value + RateUnitEnum (bps/kbps/Mbps/Gbps/Tbps) - clarify Dnn description (Data Network Name)

cmhkknight added 2 commits July 22, 2026 17:49

Enhance API with User Experience Insights support

3f5bf62

Added User Experience Insights section and related schemas for subscription details, including UserExperienceInsightsSubscriptionDetail and UserExperienceInsightsRecords.

Enhance API documentation for user experience insights

c226643

Added user experience insights API details including request and response structures for application experience analysis.

cmhkknight requested review from Kevsy, maheshc01 and urvika-v as code owners July 22, 2026 09:58

maheshc01 marked this pull request as draft July 29, 2026 15:42

XunliYang added 3 commits August 26, 2026 11:31

Merge remote-tracking branch 'upstream/main'

24f3e3b

fix: user-experience-insight schema align with commonalities

0912002

fix camara validation error

5dc6f7d

maheshc01 marked this pull request as ready for review August 26, 2026 15:10

XunliYang added 3 commits August 27, 2026 18:22

fix: add pattern or enum for string type

66eee97

fix: fix duplicate scenario name

a375624

Kevsy reviewed Aug 28, 2026

View reviewed changes

Kevsy requested changes Aug 28, 2026

View reviewed changes

XunliYang reviewed Sep 1, 2026

View reviewed changes

Traffic Class	Typical Applications	Key QoS Characteristic
Conversational	Voice calls, video calls, telepresence	Very low delay and jitter
Streaming	Video/audio streaming	Continuous media flow; some delay acceptable
Interactive	Web browsing, database queries, online transactions	Low response time important
Background	Email, file transfer, backups, software downloads	Delay insensitive; reliability more important

Uh oh!

Conversation

cmhkknight commented Jul 22, 2026

What type of PR is this?

What this PR does / why we need it:

Which issue(s) this PR fixes:

Special notes for reviewers:

Changelog input

Additional documentation

Uh oh!

XunliYang commented Jul 28, 2026

Uh oh!

benhepworth commented Jul 29, 2026

Uh oh!

XunliYang commented Aug 28, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Kevsy Aug 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Kevsy left a comment

Choose a reason for hiding this comment

Uh oh!

XunliYang commented Aug 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

XunliYang left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Kevsy Aug 28, 2026 •

edited

Loading

XunliYang commented Aug 31, 2026 •

edited

Loading