Skip to main content
Technology

Network APIs for Connectivity Quality

At a glance
  • What it is: an index of the CAMARA network APIs 5G-MAG analyses for media production and distribution.
  • Why it matters: a media application sees a small REST resource, while the operator's platform does the work behind it.
  • Where it stands: under development and subject to change, reflecting outcomes elaborated by 5G-MAG members.
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

Network API Initiatives under analysis​

5G-MAG analyses the open-source CAMARA APIs, which provide developer-friendly abstractions of network capabilities, for media use cases.

This section contains information on:

CAMARA APIs for Communication Quality Management​

The CAMARA APIs below are analysed on their own pages. They are not all independent: several depend on the QoS Profiles API (which lists the named QoS bundles an operator offers) or on the Application Profiles API (which declares an application's requirements once for reuse). The table gives each API's role and its main dependency at a glance; the sections that follow link to the analysis and to the CAMARA source (CAMARA ApplicationProfiles main@11066d6 application-profiles.yaml info.description; CAMARA QoSProfiles main@8ce8f4d qos-profiles.yaml info.description; CAMARA ConnectivityInsights main@db9c0de connectivity-insights.yaml info.description).

APIWhat it doesMain dependency
Application ProfilesDeclare an application's network and compute requirements once, for reuse by other APIs.none (CAMARA ApplicationProfiles main@11066d6 application-profiles.yaml info.description)
Connectivity InsightsOne-shot check of whether the network can currently meet those requirements.Application Profiles (CAMARA ConnectivityInsights main@db9c0de connectivity-insights.yaml info.description)
Connectivity Insights SubscriptionsContinuous monitoring of the same, delivered as event notifications.Application Profiles (CAMARA ConnectivityInsights main@db9c0de connectivity-insights-subscriptions.yaml info.description; schemas applicationProfileId; event type org.camaraproject.connectivity-insights-subscriptions.v0.network-quality)
Dedicated NetworksReserve a dedicated network for an area and time, then grant devices access.Dedicated Network Profiles or QoS Profiles
Network Slice BookingBook network slice resources for an area and time window.none (defines its own slice QoS profile) (CAMARA NetworkSliceBooking main@fc349ef network-slice-booking.yaml info.description; schemas SliceQosProfile)
QoS BookingReserve a QoS profile in advance for a specific device.QoS Profiles (CAMARA QoSBooking main@4de93f1 qos-booking.yaml info.description)
QoS Booking and AssignmentReserve a QoS profile for a device count, then assign devices later.QoS Profiles (CAMARA QoSBooking main@4de93f1 qos-booking-and-assignment.yaml info.description; schemas bookingDeviceCount)
QoS ProfilesDiscover the named QoS profiles an operator offers.none (consulted first by most QoS APIs) (CAMARA QoSProfiles main@8ce8f4d qos-profiles.yaml info.description; CAMARA QoSBooking main@4de93f1 qos-booking.yaml info.description; CAMARA QoSBooking main@4de93f1 qos-booking-and-assignment.yaml info.description)
QoS ProvisioningAssign a QoS profile to a device indefinitely.QoS Profiles (CAMARA QualityOnDemand main@471aa35 qos-provisioning.yaml info.description)
Quality on DemandRequest a QoS session for the duration of a media flow.QoS Profiles (CAMARA QualityOnDemand main@471aa35 quality-on-demand.yaml info.description; /sessions POST)

Application Profiles API​

Declares an application's network and compute requirements once, so other APIs can reference them (CAMARA ApplicationProfiles main@11066d6 application-profiles.yaml info.description).

Connectivity Insights API​

One-shot check of whether the network can currently meet an application's requirements (CAMARA ConnectivityInsights main@db9c0de connectivity-insights.yaml info.description).

Connectivity Insights Subscriptions API​

Continuous version of Connectivity Insights, delivering event notifications when network quality changes (CAMARA ConnectivityInsights main@db9c0de connectivity-insights-subscriptions.yaml info.description; schemas event network-quality; callback description).

Dedicated Networks API​

Reserves a dedicated network for an area and time window, then grants specific devices access (CAMARA DedicatedNetworks main@81bcd9d dedicated-network.yaml info.description; CAMARA DedicatedNetworks main@81bcd9d dedicated-network-accesses.yaml info.description).

Network Slice Booking API​

Books network slice resources for an area and time window ahead of an event (CAMARA NetworkSliceBooking main@fc349ef network-slice-booking.yaml info.description).

QoS Booking APIs​

Reserves a QoS profile in advance for a specific device (CAMARA QoSBooking main@4de93f1 qos-booking.yaml info.description).

QoS Booking and Assignment APIs​

Reserves a QoS profile for a number of devices, then assigns individual devices to the booking later (CAMARA QoSBooking main@4de93f1 qos-booking-and-assignment.yaml info.description).

QoS Profiles API​

Lists the named QoS profiles an operator offers; consulted first by most of the QoS APIs above (CAMARA QoSProfiles main@8ce8f4d qos-profiles.yaml info.description; CAMARA QoSBooking main@4de93f1 qos-booking.yaml info.description).

QoS Provisioning API​

Assigns a QoS profile to a device indefinitely, until the provisioning is deleted (CAMARA QualityOnDemand main@471aa35 qos-provisioning.yaml info.description).

Quality On Demand API​

Requests a QoS session (stable latency or prioritised throughput) for the duration of a media flow (CAMARA QualityOnDemand main@471aa35 quality-on-demand.yaml info.description; /sessions POST).

Details on the device object​

A device object in the sense of CAMARA APIs is defined by the common Device schema (CAMARA Commonalities main@b1a9f08 CAMARA_common.yaml schemas Device, DeviceIpv4Address, DeviceIpv6Address; Glossary.md). It needs at least one identifier; an ipv4Address object needs a publicAddress and at least one of privateAddress and publicPort. The example below combines several identifiers for illustration (CAMARA QualityOnDemand main@471aa35 quality-on-demand.yaml components/examples EXAMPLE_4_CREATION_BODY):

{
"device": {
"phoneNumber": "+123456789",
"ipv4Address": {
"publicAddress": "203.0.113.0",
"publicPort": 59765
},
"ipv6Address": "2001:db8:85a3:8d3:1319:8a2e:370:7344"
}
}

However, as indicated in the Production and Contribution Scenarios, a device in the context of a Mobile Journalism or Media Production scenario may be:

  • A single User Equipment (UE, the mobile termination that attaches to the network, for example a smartphone) equipped with a single Subscriber Identity Module (SIM) card (or embedded SIM, eSIM) connected to the mobile network.
  • A single device (e.g. a smartphone) equipped with 2 UEs each with 1 SIM card (or eSIM) connected to a different carrier of the same mobile network or different mobile networks.
  • A device with multiple UEs (e.g. a cellular bonding backpack) equipped with multiple SIM cards each one connected to a different carrier of the same mobile network or connected to different mobile networks.

Identifying such a device by a telephone number (Mobile Station International Subscriber Directory Number, MSISDN) may not be practical (or relevant) as the device is used exclusively for data.

Details on the Application Server​

A media application running in a device (as per the sense in the section above) may run different processes each one associated to a different Application Server (AS, the server endpoint the media flows to or from) IP:port address. For instance, an application for Mobile Journalism may be running uplink video towards an AS and receiving return video from a different IP:port. These two different media flows, though belonging to the same device, would require the allocation of different network resources and performance.

Relevant QoS Parameters​

Both the Application Profiles API and the QoS Profiles API reuse the same core network-quality parameters, defined once below. The QoS Profiles API adds a few extra fields; the Network Slice Booking API uses a separate set. (Note: the field for error loss rate appears as packetErrorLossRate in the CAMARA QoS Profiles definition; some API definitions spell it packetLossErrorRate. Confirm the exact name against the specific .yaml you integrate against.) (CAMARA QoSProfiles main@8ce8f4d qos-profiles.yaml schemas packetErrorLossRate and extra fields; CAMARA ApplicationProfiles main@11066d6 application-profiles.yaml schemas PacketErrorLossRate; CAMARA NetworkSliceBooking main@fc349ef network-slice-booking.yaml schemas SliceQosProfile)

Core network-quality parameters (Application Profiles and QoS Profiles)​

  • packetDelayBudget- the maximum allowable one-way latency between the customer's device and the gateway from the operator's network to other networks. The end-to-end or round trip latency will be about two times this value plus the latency not controlled by the operator (CAMARA QoSProfiles main@8ce8f4d qos-profiles.yaml schemas packetDelayBudget; CAMARA ApplicationProfiles main@11066d6 application-profiles.yaml schemas PacketDelayBudget)
  • targetMinDownstreamRate - the target minimum downstream rate (CAMARA QoSProfiles main@8ce8f4d qos-profiles.yaml schemas targetMinDownstreamRate; CAMARA ApplicationProfiles main@11066d6 application-profiles.yaml schemas TargetMinDownstreamRate).
  • targetMinUpstreamRate - the target minimum upstream rate (CAMARA QoSProfiles main@8ce8f4d qos-profiles.yaml schemas targetMinUpstreamRate; CAMARA ApplicationProfiles main@11066d6 application-profiles.yaml schemas TargetMinUpstreamRate)
  • packetErrorLossRate - the exponential power of the allowable error loss rate 10^(-N). The field name is spelled packetErrorLossRate in the QoS Profiles definition, packetLossErrorRate in the Application Profiles definition and packetlossErrorRate in the Connectivity Insights definitions (CAMARA QoSProfiles main@8ce8f4d qos-profiles.yaml QosProfile; CAMARA ApplicationProfiles main@11066d6 application-profiles.yaml; CAMARA ConnectivityInsights main@db9c0de connectivity-insights.yaml).
  • jitter - this 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) (CAMARA QoSProfiles main@8ce8f4d qos-profiles.yaml schemas jitter; CAMARA ApplicationProfiles main@11066d6 application-profiles.yaml schemas Jitter).

Additional QoS Profiles parameters​

The QoS Profiles API adds further fields on top of the core parameters above, for example:

  • minDuration (CAMARA QoSProfiles main@8ce8f4d qos-profiles.yaml schemas minDuration)
  • maxDuration (CAMARA QoSProfiles main@8ce8f4d qos-profiles.yaml schemas maxDuration)
  • priority (CAMARA QoSProfiles main@8ce8f4d qos-profiles.yaml schemas priority)
  • l4sQueueType (CAMARA QoSProfiles main@8ce8f4d qos-profiles.yaml schemas l4sQueueType)

Network Slice QoS Profile​

  • maxNumOfDevices- is the maximum number of devices that can be connected to the slice (CAMARA NetworkSliceBooking main@fc349ef network-slice-booking.yaml schemas SliceQosProfile.maxNumOfDevices)
  • downStreamRatePerDevice - is the maximum downstream rate allowed for each device connected to the slice. It indicates the individual device capability required for the slice (CAMARA NetworkSliceBooking main@fc349ef network-slice-booking.yaml schemas SliceQosProfile.downStreamRatePerDevice).
  • upStreamRatePerDevice - is the maximum upstream rate allowed for each device connected to the slice. It indicates the individual device capability required for the slice (CAMARA NetworkSliceBooking main@fc349ef network-slice-booking.yaml schemas SliceQosProfile.upStreamRatePerDevice).
  • downStreamDelayBudget - is the maximum allowable downlink packet transmission latency (millisecond). By limiting the delay, the network can provide an acceptable level of performance for various services, such as voice calls, video streaming, and data (CAMARA NetworkSliceBooking main@fc349ef network-slice-booking.yaml schemas SliceQosProfile.downStreamDelayBudget).
  • upStreamDelayBudget - is the maximum allowable uplink packet transmission latency (millisecond). By limiting the delay, the network can provide an acceptable level of performance for various services, such as voice calls, video streaming, and data (CAMARA NetworkSliceBooking main@fc349ef network-slice-booking.yaml schemas SliceQosProfile.upStreamDelayBudget).

Cross-cutting CAMARA rules (Commonalities)​

The APIs analysed in this section share a set of conventions defined by the CAMARA Commonalities and Identity and Consent Management working groups, rather than being redefined per API (CAMARA Commonalities main@b1a9f08 CAMARA-API-Design-Guide.md section 6.1 and 6.2; CAMARA QualityOnDemand main@471aa35 quality-on-demand.yaml info.description):

  • Device identification. The common Device schema has four properties, of which at least one must be present: phoneNumber (the MSISDN, in E.164 format with a leading +), ipv4Address, ipv6Address and networkAccessIdentifier (a subscription identifier managed by each operator). The operator may support only a subset of them; the API consumer can give several, and the API provider then uses one of them without checking that they match. The schema says that CAMARA does not currently allow the use of networkAccessIdentifier, and the definitions of Quality on Demand, QoS Provisioning and Connectivity Insights Subscriptions state that it "is defined for future use and will not be supported with this version of the API" (CAMARA Commonalities main@b1a9f08 CAMARA_common.yaml schemas Device, PhoneNumber, NetworkAccessIdentifier; CAMARA QualityOnDemand main@471aa35 quality-on-demand.yaml info.description; qos-provisioning.yaml info.description; CAMARA ConnectivityInsights main@db9c0de connectivity-insights-subscriptions.yaml info.description). When a three-legged token identifies the subscriber the device object must not be provided (422 UNNECESSARY_IDENTIFIER otherwise); when the subscriber cannot be identified from the token or the device object, 422 MISSING_IDENTIFIER is returned; 422 UNSUPPORTED_IDENTIFIER is returned when none of the identifiers given is supported (CAMARA Commonalities main@b1a9f08 CAMARA_common.yaml responses DeviceIdentifier422 and examples GENERIC_422_MISSING_IDENTIFIER_DEVICE, GENERIC_422_UNSUPPORTED_IDENTIFIER_DEVICE, GENERIC_422_UNNECESSARY_IDENTIFIER_DEVICE; CAMARA-API-Design-Guide.md Appendix A; Glossary.md).
  • Authorisation. OAuth 2.0, with a three-legged token (the OIDC Authorization Code Flow or CIBA, which authenticate the end user) identifying the subscriber, or a two-legged (client credentials) token with the device given explicitly; many of these APIs accept either. The Security and Interoperability Profile lets the client credentials grant be used only if the API consumer and the API provider have agreed it, and the API definitions make a three-legged token mandatory where personal data is processed and users can opt in or out (CAMARA IdentityAndConsentManagement main@f922b8a CAMARA-Security-Interoperability.md Introduction, Client Credentials Flow; CAMARA QualityOnDemand main@471aa35 quality-on-demand.yaml info.description Authorization and authentication).
  • Notifications. CloudEvents 1.0 JSON delivered to a sink callback URL (an https URL), authenticated per sinkCredential (a credentialType of ACCESSTOKEN or PRIVATE_KEY_JWT); each event has the required attributes id, source, specversion, type and time, and a data object (CAMARA Commonalities main@b1a9f08 CAMARA-API-Event-Subscription-and-Notification-Guide.md section 2.1, section 3.1; CAMARA_event_common.yaml schemas CloudEvent, Sink, SinkCredential).
  • Tracing and errors. An optional x-correlator header is echoed back, and a common error model is used across APIs (CAMARA Commonalities main@b1a9f08 CAMARA-API-Design-Guide.md section 5.8.5, section 3.2).
  • Versioning and releases. A wip version on main is not a release. Several APIs here still have v0 event types, so field names and enumerations can change.

How it works​

A CAMARA API is deliberately thin: the media application sees a small REST resource, for example a QoD session or a slice booking. The operator's platform does the work behind it.

API / specificationWhat it does for media
CAMARA Quality on Demand (QoD) APIRequests stable latency or prioritised throughput for a media flow on demand, for example a low-latency contribution link. (CAMARA QualityOnDemand main@471aa35 quality-on-demand.yaml info.description; /sessions POST)
CAMARA Connectivity Insights APIChecks whether the network can currently meet an application's quality requirements before or during a session. (CAMARA ConnectivityInsights main@db9c0de connectivity-insights.yaml info.description; CAMARA ConnectivityInsights main@db9c0de connectivity-insights-subscriptions.yaml info.description)
CAMARA Network Slice Booking APIReserves network slice resources for a given area and time window ahead of an event. (CAMARA NetworkSliceBooking main@fc349ef network-slice-booking.yaml info.description)

This is the value CAMARA adds: one operator-agnostic contract in place of per-operator integration. It is also the source of most of the open questions 5G-MAG records on the CAMARA API pages, because information that exists inside the network (measured latency, service-area availability) is not always surfaced back through the CAMARA abstraction.

API families. The CAMARA APIs 5G-MAG analyses fall into a few families: QoS for a flow or device (Quality on Demand, QoS Provisioning, QoS Booking and QoS Booking and Assignment, all consuming a named profile from QoS Profiles); area and time reservation for many devices (Network Slice Booking and Dedicated Networks); and requirements and monitoring (Application Profiles declares an application's needs once, and Connectivity Insights plus Connectivity Insights Subscriptions check whether the network can meet them). On main, all of these API definitions are work-in-progress (wip) versions and all event types except Quality on Demand's are v0, so field names and enumerations can change between releases (CAMARA QualityOnDemand main@471aa35 quality-on-demand.yaml schemas QosEventType; info.version; CAMARA QualityOnDemand main@471aa35 qos-provisioning.yaml QosProvisioningEventType).

Two further sets of pages apply this to real workflows: Content Production & Contribution covers professional content production and contribution scenarios, and Live Media Distribution covers the visibility gap between content providers and network operators for live distribution.

Related: Media Streaming and Advanced Media Delivery