- 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.
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
- Details on the DEVICE object
- Details on the APPLICATION SERVER
- Relevant QoS parameters
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).
| API | What it does | Main dependency |
|---|---|---|
| Application Profiles | Declare an application's network and compute requirements once, for reuse by other APIs. | none (CAMARA ApplicationProfiles main@11066d6 application-profiles.yaml info.description) |
| Connectivity Insights | One-shot check of whether the network can currently meet those requirements. | Application Profiles (CAMARA ConnectivityInsights main@db9c0de connectivity-insights.yaml info.description) |
| Connectivity Insights Subscriptions | Continuous 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 Networks | Reserve a dedicated network for an area and time, then grant devices access. | Dedicated Network Profiles or QoS Profiles |
| Network Slice Booking | Book 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 Booking | Reserve a QoS profile in advance for a specific device. | QoS Profiles (CAMARA QoSBooking main@4de93f1 qos-booking.yaml info.description) |
| QoS Booking and Assignment | Reserve 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 Profiles | Discover 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 Provisioning | Assign a QoS profile to a device indefinitely. | QoS Profiles (CAMARA QualityOnDemand main@471aa35 qos-provisioning.yaml info.description) |
| Quality on Demand | Request 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).
- Analysis of Application Profiles by 5G-MAG
- CAMARA Project: Application Profiles project page and GitHub repository (CAMARA ApplicationProfiles main@11066d6 application-profiles.yaml externalDocs url)
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).
- Analysis of Connectivity Insights by 5G-MAG
- CAMARA Project: Connectivity Insights project page and GitHub repository (CAMARA ConnectivityInsights main@db9c0de connectivity-insights.yaml externalDocs url)
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).
- Analysis of Connectivity Insights Subscriptions by 5G-MAG
- CAMARA Project: Connectivity Insights Subscriptions project page and GitHub repository (CAMARA ConnectivityInsights main@db9c0de connectivity-insights.yaml externalDocs url)
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).
- Analysis of Dedicated Networks by 5G-MAG
- CAMARA Project: Dedicated Networks project page and GitHub repository (CAMARA DedicatedNetworks main@81bcd9d dedicated-network.yaml externalDocs url)
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).
- Analysis of Network Slice Booking by 5G-MAG
- CAMARA Project: Network Slice Booking project page and GitHub repository (CAMARA NetworkSliceBooking main@fc349ef network-slice-booking.yaml externalDocs url)
QoS Booking APIs
Reserves a QoS profile in advance for a specific device (CAMARA QoSBooking main@4de93f1 qos-booking.yaml info.description).
- Analysis of QoS Booking by 5G-MAG
- CAMARA Project: QoS Booking project page and GitHub repository (CAMARA QoSBooking main@4de93f1 qos-booking.yaml externalDocs url)
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).
- Analysis of QoS Booking and Assignment by 5G-MAG
- CAMARA Project: QoS Booking and Assignment project page and GitHub repository (CAMARA QoSBooking main@4de93f1 qos-booking.yaml externalDocs url)
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).
- Analysis of QoS Profiles by 5G-MAG
- CAMARA Project: QoS Profiles project page and GitHub repository (CAMARA QoSProfiles main@8ce8f4d qos-profiles.yaml externalDocs; CAMARA QualityOnDemand main@471aa35 quality-on-demand.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).
- Analysis of QoS Provisioning by 5G-MAG
- CAMARA Project: QoS Provisioning project page and GitHub repository (CAMARA QualityOnDemand main@471aa35 quality-on-demand.yaml externalDocs url)
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).
- Analysis of Quality On Demand by 5G-MAG
- CAMARA Project: Quality on Demand project page and GitHub repository (CAMARA QualityOnDemand main@471aa35 quality-on-demand.yaml externalDocs url)
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 spelledpacketErrorLossRatein the QoS Profiles definition,packetLossErrorRatein the Application Profiles definition andpacketlossErrorRatein 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
Deviceschema has four properties, of which at least one must be present:phoneNumber(the MSISDN, in E.164 format with a leading+),ipv4Address,ipv6AddressandnetworkAccessIdentifier(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 ofnetworkAccessIdentifier, 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 thedeviceobject must not be provided (422 UNNECESSARY_IDENTIFIERotherwise); when the subscriber cannot be identified from the token or thedeviceobject,422 MISSING_IDENTIFIERis returned;422 UNSUPPORTED_IDENTIFIERis 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
sinkcallback URL (anhttpsURL), authenticated persinkCredential(acredentialTypeofACCESSTOKENorPRIVATE_KEY_JWT); each event has the required attributesid,source,specversion,typeandtime, and adataobject (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-correlatorheader 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
wipversion onmainis not a release. Several APIs here still havev0event 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 / specification | What it does for media |
|---|---|
| CAMARA Quality on Demand (QoD) API | Requests 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 API | Checks 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 API | Reserves 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