Network APIs for Connectivity Quality

CAMARA Connectivity Insights Subscriptions

warning

This documentation is currently under development and subject to change. It reflects outcomes elaborated by 5G-MAG members. If you are interested in becoming a member of the 5G-MAG and actively participating in shaping this work, please contact the Project Office

Description

The "Connectivity Insights Subscriptions" API lets application developers receive continuous updates about network quality through event notifications. This allows developers to monitor network performance for their application users and receive alerts when network conditions change, helping them take informed decisions related to optimizing the application's end user experience (CAMARA ConnectivityInsights main@db9c0de connectivity-insights-subscriptions.yaml info.description; /subscriptions POST callbacks notifications description).

This API is the continuous counterpart to the one-shot Connectivity Insights API: instead of a single check, the consumer subscribes once and the network pushes notifications when quality changes (CAMARA ConnectivityInsights main@db9c0de connectivity-insights.yaml info.description API functionality; CAMARA ConnectivityInsights main@db9c0de connectivity-insights-subscriptions.yaml /subscriptions POST callbacks notifications).

Information: Connectivity Insights Subscriptions project page and GitHub repository

The API definitions can be obtained here: ConnectivityInsights API_definitions folder

The Connectivity Insights Subscriptions API definition (YAML) is available at: connectivity-insights-subscriptions.yaml

Operations and dependencies

Connectivity Insights Subscriptions API

• POST /subscriptions with the request body containing sink, protocol, types and a config with subscriptionDetail (device, applicationServer, applicationServerPorts, applicationProfileId) and optionally subscriptionExpireTime, subscriptionMaxEvents and initialEvent. Response contains the subscription id.
  • Dependency: Requires applicationProfileId from a previous call to the Application Profiles API (CAMARA ConnectivityInsights main@db9c0de connectivity-insights-subscriptions.yaml CreateSubscriptionDetail required applicationProfileId, applicationServer).
• GET /subscriptions - Operation to list subscriptions authorised to be retrieved by the provided access token (CAMARA ConnectivityInsights main@db9c0de connectivity-insights-subscriptions.yaml /subscriptions GET description).
• GET /subscriptions/{subscriptionId} - Retrieve a given subscription by ID (CAMARA ConnectivityInsights main@db9c0de connectivity-insights-subscriptions.yaml /subscriptions/{subscriptionId} GET description).
• DELETE /subscriptions/{subscriptionId} - Delete a given subscription by ID (CAMARA ConnectivityInsights main@db9c0de connectivity-insights-subscriptions.yaml /subscriptions/{subscriptionId} DELETE description)

Standardisation context

This API is the event-driven counterpart of the one-shot Connectivity Insights check. It follows the CAMARA "explicit subscription" pattern defined by the Commonalities working group: the consumer creates a subscription resource with POST /subscriptions, supplies a sink callback URL and the types of event it wants, and the provider then pushes notifications instead of the consumer polling. This is the same subscription/notification model used by the other event-bearing APIs on this portal (for example Quality on Demand and QoS Booking and Assignment), and it maps conceptually onto the NEF monitoring-event subscription mechanism in the 5G Core (TS 29.522), where an Application Function subscribes to be notified of network events rather than querying repeatedly.

Notifications are CloudEvents 1.0 JSON documents. The subscription carries a lifetime and a cap: subscriptionExpireTime bounds how long it remains active and subscriptionMaxEvents bounds how many events are delivered before it closes. initialEvent: true requests an event as soon as the subscription is created if the current situation reflects the event request; that event counts towards subscriptionMaxEvents. Where present, sinkCredential describes how the provider authenticates to the consumer's sink.

As with the one-shot API, the payload is qualitative (per-threshold indications against the referenced application profile), so the same media limitation applies: the consumer learns that quality changed but not the measured value. For a media workflow the value of the subscription form is timeliness. A production can react (drop resolution, switch bonding path, request a QoS boost) at the moment quality degrades, without polling. The trade-off is that delivery depends on the consumer's sink being reachable and correctly authenticated.

Workflow: Media application subscribing to Connectivity Insights events

A user of a media application would like to obtain Connectivity Insights events. An example figure is shown in the context of using Application Profiles and Connectivity Insights. The following steps are executed:

An Application Profile is created first (Step 0), then a subscription is created (Step 1) that delivers recurring network-quality notifications.

Step 0: Pre-conditions

• Create an application profile using the Application Profiles API (with the relevant application requirements) (CAMARA ConnectivityInsights main@db9c0de connectivity-insights.yaml info.description API functionality usage step 1; CAMARA ConnectivityInsights main@db9c0de connectivity-insights-subscriptions.yaml CreateSubscriptionDetail.applicationProfileId).
• Create a device object for the device which media flow is to be monitored (CAMARA ConnectivityInsights main@db9c0de connectivity-insights-subscriptions.yaml CreateSubscriptionDetail.device; info.description Relevant terms).
• Obtain IP address and port of the application server (Ingest Server of Production).

Step 1: Subscribe to recurrent events/notifications on network quality

• POST /subscriptions, passing the applicationProfileId obtained in step 0, the address/port of an application server, and a device object. Indicate expiration time and maximum number of events (CAMARA ConnectivityInsights main@db9c0de connectivity-insights-subscriptions.yaml /subscriptions POST; Config.subscriptionExpireTime/subscriptionMaxEvents via CAMARA Commonalities main@b1a9f08 CAMARA-API-Event-Subscription-and-Notification-Guide.md section 2.2.3).

5G-MAG's Self-Assessment

This section records 5G-MAG's practical reading of the API and the open points it raises for media use.

The APIs are likely to be invoked to obtain information about the ability of the network to meet the requirements during operation. However:

• The information received is qualitative (e.g. "targetMinDownstreamRate": "meets the application requirements"). An application would be unable to understand which parameters to be adapted in order to revert a situation in which requirements cannot be met.

Potential improvements:

• If used to monitor resources for which QoS was requested (via a different API) harmonisation of Application Profile and QoS Profile for consistency.
• an indication of the actual performance parameters (quantitative) for those defined in the Application Profile may provide better insight for potential remedies. E.g. latency cannot be fulfilled, but please respond with the actual latency the link device-AS is experiencing.

---

Application Profiles API Usage

Check: Application Profiles API. The type of parameters that an applicationProfile defines is shown below (CAMARA ApplicationProfiles main@11066d6 application-profiles.yaml ApplicationProfile; NetworkQualityThresholds; ComputeResourcesThresholds).

{
  "networkQualityThresholds": {
    "packetDelayBudget": {
      "value": 12,
      "unit": "Milliseconds"
    },
    "targetMinDownstreamRate": {
      "value": 10,
      "unit": "Mbps"
    },
    "targetMinUpstreamRate": {
      "value": 10,
      "unit": "Mbps"
    },
    "packetLossErrorRate": 3,
    "jitter": {
      "value": 12,
      "unit": "Milliseconds"
    }
  },
  "computeResources": {
    "targetMinCPU": 0.5,
    "targetMinMemory": {
      "value": 10,
      "unit": "MB"
    },
    "gpuVendorType": "Nvidia",
    "gpuModelName": "string",
    "targetMinGPU": 1,
    "targetMinGPUMemory": {
      "value": 10,
      "unit": "MB"
    },
    "targetMinEphemeralStorage": {
      "value": 10,
      "unit": "MB"
    },
    "targetMinPersistentStorage": {
      "value": 10,
      "unit": "MB"
    }
  }
}

Device object

This is how a device is defined (CAMARA QualityOnDemand main@471aa35 quality-on-demand.yaml examples; CAMARA ConnectivityInsights main@db9c0de connectivity-insights-subscriptions.yaml info.description Relevant terms; CAMARA Commonalities main@b1a9f08 Glossary.md Phone Number):

{
  "device": {
    "phoneNumber": "+123456789",
    "networkAccessIdentifier": "123456789@domain.com",
    "ipv4Address": {
      "publicAddress": "84.125.93.10",
      "publicPort": 59765
    },
    "ipv6Address": "2001:db8:85a3:8d3:1319:8a2e:370:7344"
  }
}

Connectivity Insights Subscriptions API Usage

Create a subscription for a device

With POST /subscriptions (CAMARA ConnectivityInsights main@db9c0de connectivity-insights-subscriptions.yaml /subscriptions POST)

The request below creates a subscription. The key fields are (CAMARA ConnectivityInsights main@db9c0de connectivity-insights-subscriptions.yaml SubscriptionRequest; Config):

Parameter	Description
sink	the callback URL to which the network delivers notifications (the consumer's endpoint must accept HTTP POST). (CAMARA ConnectivityInsights main@db9c0de connectivity-insights-subscriptions.yaml /subscriptions POST callbacks notifications; CAMARA Commonalities main@b1a9f08 CAMARA-API-Event-Subscription-and-Notification-Guide.md section 2.2.3)
sinkCredential	the credential the API provider uses to authenticate against that endpoint (optional; not used in the example).
types	the event types the consumer subscribes to (here, network-quality change events). (CAMARA ConnectivityInsights main@db9c0de connectivity-insights-subscriptions.yaml SubscriptionRequest.types; ApiEventType)
initialEvent	when true, an event is sent as soon as the subscription is created if the current situation reflects the event request (it counts towards subscriptionMaxEvents).

{
  "protocol": "HTTP",
  "sink": "https://endpoint.example.com/sink",
  "types": ["org.camaraproject.connectivity-insights-subscriptions.v0.network-quality"],
  "config": {
    "subscriptionDetail": {
      "device": {
        "phoneNumber": "+123456789",
        "networkAccessIdentifier": "123456789@domain.com",
        "ipv4Address": {
          "publicAddress": "84.125.93.10",
          "publicPort": 59765
        },
        "ipv6Address": "2001:db8:85a3:8d3:1319:8a2e:370:7344"
      },
      "applicationServer": {
        "ipv4Address": "192.168.0.1/24",
        "ipv6Address": "2001:db8:85a3:8d3:1319:8a2e:370:7344"
      },
      "applicationServerPorts": {
        "ranges": [
          {
            "from": 5010,
            "to": 5020
          }
        ],
        "ports": [5060, 5070]
      },
      "applicationProfileId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
    },
    "subscriptionExpireTime": "2023-07-03T12:27:08.312Z",
    "subscriptionMaxEvents": 5,
    "initialEvent": true
  }
}

Type of response: A subscription object. The response echoes the subscription configuration and adds the assigned id, startsAt/expiresAt window, and current status:

{
  "protocol": "HTTP", "sink": "https://endpoint.example.com/sink",
  "types": ["org.camaraproject.connectivity-insights-subscriptions.v0.network-quality"],
  "config": {
    "subscriptionDetail": {
      "device": {
        "phoneNumber": "+123456789",
        "networkAccessIdentifier": "123456789@domain.com",
        "ipv4Address": {
          "publicAddress": "84.125.93.10",
          "publicPort": 59765
        },
        "ipv6Address": "2001:db8:85a3:8d3:1319:8a2e:370:7344"
      },
      "applicationServer": {
        "ipv4Address": "192.168.0.1/24",
        "ipv6Address": "2001:db8:85a3:8d3:1319:8a2e:370:7344"
      },
      "applicationServerPorts": {
        "ranges": [
          {
            "from": 5010,
            "to": 5020
          }
        ],
        "ports": [5060, 5070]
      },
      "applicationProfileId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
    },
    "subscriptionExpireTime": "2023-07-03T12:27:08.312Z",
    "subscriptionMaxEvents": 5,
    "initialEvent": true
  },
  "id": "1119920371",
  "startsAt": "2023-07-03T12:27:08.312Z",
  "expiresAt": "2023-07-03T12:27:08.312Z",
  "status": "ACTIVATION_REQUESTED"
}

---

Event notifications

The whole point of this API is asynchronous delivery: once a subscription is created, the network pushes an event to the consumer whenever a connectivity event changes the network's ability to meet the application's demands (and, if initialEvent is true, also as soon as the subscription is created if the current situation reflects the event request), rather than the consumer polling.

Mechanism

Notifications are delivered to the callback URL supplied as the sink parameter when the subscription is created with POST /subscriptions (see the request example above). Where present, sinkCredential describes the credential the API provider uses to authenticate against that endpoint. The consumer's sink must accept HTTP POST requests carrying the notification payload. The subscription stops delivering when it expires (subscriptionExpireTime) or reaches its event cap (subscriptionMaxEvents) (CAMARA ConnectivityInsights main@db9c0de connectivity-insights-subscriptions.yaml /subscriptions POST callbacks notifications; CAMARA Commonalities main@b1a9f08 CAMARA-API-Event-Subscription-and-Notification-Guide.md section 2.2.3, 2.2.5).

The payload follows the CloudEvents 1.0 specification (JSON format) (CAMARA Commonalities main@b1a9f08 CAMARA-API-Event-Subscription-and-Notification-Guide.md section 3.1; CAMARA ConnectivityInsights main@db9c0de connectivity-insights-subscriptions.yaml callbacks notifications content application/cloudevents+json).

Event types

Event type	Meaning
org.camaraproject.connectivity-insights-subscriptions.v0.network-quality	The network quality relative to the subscribed application profile changed. (CAMARA ConnectivityInsights main@db9c0de connectivity-insights-subscriptions.yaml ApiEventType; EventNetworkQuality; callbacks notifications description)

The data object carries the network-quality assessment (the same qualitative per-threshold indications returned by the one-shot Connectivity Insights check, plus the applicationProfileId). The v0 segment in the event type is the event version; for an initial API the event version starts at v0, and stable APIs use a version greater than 0.

note

The event type and payload structure above are taken from the CAMARA Connectivity Insights Subscriptions API definition. Confirm the exact values against the connectivity-insights-subscriptions.yaml for the version you are integrating against, as they can change between releases (CAMARA ConnectivityInsights main@db9c0de connectivity-insights-subscriptions.yaml ApiEventType; EventNetworkQuality; CAMARA Commonalities main@b1a9f08 CAMARA-API-Event-Subscription-and-Notification-Guide.md section 2.3 Event Versioning).