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
Using CAMARA APIs (and Network Services) for Content Production & Contribution
This is a list of CAMARA APIs suitable to be used in the context of Connectivity Quality Management: Network API Initiatives under analysis.
Their mapping to the context of Content Production & Contribution is done below based on the different steps identified in Workflows and Requirements.
The columns of the summary table and the sections that follow are organised around five phases of using network capabilities, taken from the Workflows analysis:
- Discovery: finding out which profiles or resources are available.
- Reservation: booking resources for a time and area.
- Assignment: attaching specific devices to a booking.
- Usage: the device actually using the reserved resources.
- Notifications: monitoring and alerts while resources are in use.
Each cell states what a given API does (or "N/A") for that phase. Several APIs have a dedicated walkthrough page in this section, linked from the sections below.
Summary of available CAMARA APIs
| API | DISCOVERY | RESERVATION | ASSIGNMENT | USAGE | NOTIFICATIONS |
| Application Profiles | N/A | N/A | N/A | N/A | Defines an Application Profile to be used for notifications. |
| ConnectivityInsights | N/A | N/A | N/A | N/A | Checks network quality for an Application Profile and an already connected device. |
| ConnectivityInsightsSubscriptions | N/A | N/A | N/A | N/A | Regular notifications for an Application Profile and an already connected device. |
| DedicatedNetworks | Discovers available Network Profiles | Creates a Dedicated Network matching Network Profile, time and area | Assigns/releases devices to a Dedicated Network | Automatic when Assignment | N/A |
| NetworkSliceBooking | N/A | Creates a Network Slice (session) | Automatic for the device invoking the creation. | Automatic for the device invoking the creation. | NO |
| QoSBooking | N/A | Creates a booking matching QoS profile, time, area, device, application,... | Automatic for the device invoking the creation. | Automatic for the device invoking the creation. | N/A |
| QoSBookingAssignment | N/A | Creates a booking matching QoS profile, time, area,... | Assigns/releases devices to a booking. | Automatic when Assignment. | NO |
| QoSProfiles | Retrieves existing profiles parameters. | N/A | N/A | N/A | N/A |
| QoSProvisioning | N/A | N/A | Assigns a QoS profile to a device indefinitely (no booking, no fixed duration); the assignment is revoked on delete. | Automatic when Assignment. | N/A |
| QualityonDemand | N/A | Creates a QoS session. | Automatic for the device invoking the creation. | Automatic for the device invoking the creation. | NO |
SERVICE AREA API
In the CAMARA context, service areas are defined using geographic coordinates (a circle or a polygon) and are used in the Dedicated Networks API and the Network Slice Booking API. The service area is passed as part of the session (or network) creation request. See the Dedicated Networks and Network Slice Booking pages for the API details.
The Dedicated Networks API includes a Network Service Areas API (dedicated-network-areas.yaml) which addresses this requirement. It allows an API consumer to query the operator-defined service areas where dedicated network resources can be provisioned.
With POST /retrieve-service-areas a list of operator-defined service areas can be retrieved by passing search criteria such as:
- A specific location (
atLocationwith latitude/longitude) - An area that must overlap with the service area (
overlappingArea) - An area that must be covered by the service area (
coveringArea) - A network profile identifier (
byNetworkProfileId) or QoS profile name (byQosProfileName)
The response returns a list of service areas, each with an id, name, description, the geographical boundary, and the supported networkProfiles and qosProfiles. The areaId returned is then used in subsequent API calls (e.g. POST /networks) to associate a dedicated network booking with that operator-defined area.
There is no equivalent service area lookup API in the other CAMARA QoS-related APIs (QoS Booking, Quality on Demand, QoS Provisioning, Network Slice Booking). These APIs accept an area geometry directly in the booking request or do not support area-scoped bookings at all. The Dedicated Networks API is the only one that separates area discovery from resource reservation.
DISCOVERY API
| Mechanism to obtain available QoS profiles |
| The QoS Profiles API retrieves the QoS profile parameters available in the network. No information about the service area is linked to such a request. |
| The Dedicated Networks - Network Profiles API obtains the list of available Network Profiles, which link the QoS Profile with additional information on the aggregated UL/DL throughput for a maximum number of devices. |
There are some limitations as the information on the name of the QoS profile need to be known beforehand. It is understood that the name of the profiles would be communicated by the network operator via the Network API Platform.
| Identification of a service area and/or time/duration |
| In general the available profiles are listed for the network, not for a specific location or time/duration. It is only when booking the resources for the specific area and duration when information about the success will be available. |
There are some limitations as the information on the availability of QoS is only available at booking time and not beforehand. The Connectivity Insights APIs are also not practical as they can only be invoked at the given location. Potential remedy: Create/Adapt an API so that information on the QoS profile availability for a given location can be retrieved.
RESERVATION API
It should be possible to book QoS (to reserve network resources) for a given application or device for the intended service area and/or time/duration. This step requires:
- Mechanism to create a booking linking a profile to a service area and time/duration.
- The previous mechanism including already information about the application server and/or device.
| Mechanism to create a booking linking a profile to a service area and time/duration |
| The Dedicated Networks - Network Profiles API requests the creation of a dedicated network linking a QoS profile with a service area and time/duration. This comprises the booking of resources for a specific QoS Profile, a maximum number of devices which can make use of it, the service area and the time/duration. |
| The Network Slice Booking API requests the creation of a session with the expected service time, service area, and QoS profile. The number of devices can be specified in the QoS profile. |
| The QoS Booking & Assignment - QoS Booking API requests the creation of a QoS booking specifying the QoS profile, number of devices, service area and time/duration. |
The Quality on Demand API lacks information about the service area. Potential remedy: add information about the service area.
| The previous mechanism including already information about the application server and/or device |
| The QoS Booking API requests the creation of a QoS booking specifying the QoS profile, application server details, device details, service area and time/duration. |
| The QoS Provisioning API requests the creation of a QoS assignment specifying the QoS profile and the device. No information about the service area or time/duration is provided. |
| The Quality on Demand API requests the creation of a QoS booking specifying the QoS profile, application server details, device details, and time/duration. No information about the service area is provided. |
There are some limitations as the information on the exact device and application server may not be known beforehand or may change in the course between making the booking and using the network resources. The mechanisms defined in Dedicated Networks API and QoS Booking and Assignment are more appropriate for this case.
All the mechanisms described above allow the booking of QoS when already at the location. However, the QoS Provisioning API and Quality on Demand API are particularly targeted to this scenario, given that it is not possible to define the service area in which they are applicable beforehand. If the booking is done at the location it is also assumed that the exact devices are known, so any of the mechanisms described above would be suitable.
These same mechanisms allow network resources to be exploited for any device, but the QoS Booking API, QoS Provisioning API and Quality on Demand API require knowledge of the devices for which the booking is requested.
By contrast, if devices are not known yet at the time of booking, it is possible to use the Dedicated Networks - Network Profiles API, Network Slice Booking API and QoS Booking & Assignment - QoS Booking API to request the booking of resources without committing to use a particular device.
ASSIGNMENT API
First step is to have booked the network resources either for any device, a given number of devices or a concrete device. This implies following one of the steps below:
- Assignment and management of the booked network resources to a device
- Direct usage of the network resources when a device just connects to the network
| Assignment of the booked network resources to a particular device |
| The QoS Booking and Assignment - Device Assignment API assigns a device to an existing QoS booking. |
| The Dedicated Network - Accesses API assigns a device to an existing network profile. |
The mechanisms which detach the booking of network resources from a particular device add flexibility.
In the event that a device needs to be exchanged or the booked resources should be assigned to a different device, the following alternatives exist:
- Creating a new booking for a new device before releasing the current device
- Separation of the QoS booking w.r.t. the device, enabling re-assignment of QoS booking.
| Creating a new booking for a new device before releasing the current device |
| With the QoS Booking API, a new booking for a specific device should be created. |
| With the QoS Provisioning API, a new booking for a specific device should be created. |
| With the Quality on Demand API, a new booking for a specific device should be created. |
With the previous mechanisms there is no guarantee that new resources are available. Releasing the previous device will also imply no guarantee that those will remain available for a new booking.
| Separation of the QoS booking w.r.t. the device, enabling re-assignment of QoS booking |
| The Dedicated Network - Accesses API can request the assignment or release of a device to an existing network profile. |
| The Network Slice Booking API can bring in a new device to exploit the booked network resources. |
| The QoS Booking & Assignment - Device Assignment API can request the assignment or release of a device to an existing QoS booking. |
The mechanisms which detach the booking of network resources from a particular device add flexibility.
USAGE API
| Direct usage of the network resources when a device just connects to the network |
| With the Network Slice Booking API, the network resources are used as soon as a device connects to the network. |
| With the QoS Booking API, the network resources are used as soon as a device connects to the network. |
| With the QoS Provisioning API, the network resources are used as soon as a device connects to the network. |
| With the Quality on Demand API, the network resources are used as soon as a device connects to the network. |
For some of these mechanisms it is unclear how the network capabilities would be exploited by a device. It may be impractical when a device needs to be exchanged.
NOTIFICATIONS API
These are different alternatives, including reception of a one-shot notification (e.g. for checking whether the network is able to meet certain requirements at a given instant of time) and a subscription to receive notifications (more useful during runtime). Both start from the same pre-requisite: creating an Application Profile by invoking the Application Profiles API with a series of user-defined network quality thresholds.
One-shot notifications. Once the Application Profile exists, the Connectivity Insights API can be invoked, and its reply contains a message about the confidence of the network in meeting the network quality thresholds.
Regular notifications. Once the Application Profile exists, the Connectivity Insights Subscriptions API can instead be invoked to receive regular notifications (up to a defined limit) about the confidence of the network in meeting the network quality thresholds.
A new application profile needs to be created where tracking notifications for the original QoS Profile which many other APIs use would be more coherent. In general, one would expect that notifications/logs can be requested for any API once the network resources are being used.
Choosing an API for a production scenario
No single CAMARA API covers all five phases cleanly. The right choice depends on whether the devices are known at booking time, whether resources must be reserved for a future time and place, and whether devices need to be swapped or re-prioritised during the event.
| If you need to... | Use | Because |
|---|---|---|
| Book QoS at the point of use for one known device (short-notice MoJo) | Quality on Demand | Creates a QoS session immediately at the device's current location; no advance reservation. |
| Assign a QoS profile to a device with no fixed end (a fixed contribution point) | QoS Provisioning | Indefinite assignment, revoked on delete; no service area or duration. |
| Reserve QoS ahead of time for a known device and application server | QoS Booking | Ties booking to a device and application server at creation. |
| Reserve QoS ahead of time for a number of devices, then attach specific devices later | QoS Booking and Assignment | Separates the booking from device assignment; supports back-up devices and on-air/standby switching. |
| Reserve a dedicated network for a venue and time, discover its service areas, then attach devices | Dedicated Networks | Separates area discovery, reservation and device access; the most complete fit for multi-device productions. |
| Book slice-level resources for an area and window | Network Slice Booking | Reserves slice resources; the device that creates the session uses them automatically. |
The decisive property is whether reservation is decoupled from device assignment. Dedicated Networks and QoS Booking and Assignment decouple them, which is what makes device swaps and dynamic prioritisation (the on-air / preview / standby pattern in the Workflows page) possible without tearing down and re-creating a booking, and therefore without risking the loss of the reserved resources.
Gaps identified against the requirements
Mapping the CAMARA APIs onto the 5G-MAG requirement categories surfaces recurring gaps. These are open items in the analysis, not defects claimed against any deployment:
- No pre-booking availability lookup. The Discovery phase can list profiles and service areas, but whether a given profile can actually be reserved for a specific location and time is known only when the reservation is attempted. Connectivity Insights checks conditions only at the device's current location.
- Service area is not universal. Only the Dedicated Networks API separates area discovery (
POST /retrieve-service-areas) from reservation. Quality on Demand and QoS Provisioning cannot express a target area at all; QoS Booking / QoS Booking and Assignment accept a geometry in the request but offer no prior area lookup. - Monitoring uses a separate profile. Notifications rely on an Application Profile (Connectivity Insights) distinct from the QoS Profile that was booked, rather than tracking the booked resource directly.
- Naming collision. Two distinct APIs ("QoS Booking" and "QoS Booking and Assignment", the latter also referred to internally as a "QoS Booking" API) share confusingly similar names, and the Dedicated Networks and QoS Booking and Assignment procedures overlap substantially.
How these APIs reach the 5G Core
Whichever CAMARA API is chosen, the operator's Network API Platform translates the request into 3GPP capability-exposure procedures. A QoS session or booking resolves, through the Network Exposure Function (NEF, TS 29.522) Nnef_AFSessionWithQoS operation, to a Policy Control Function (PCF) authorisation (Npcf_PolicyAuthorization, TS 29.514) that installs a QoS Flow on the device's PDU session. Advance reservation for a future window maps to background data transfer negotiation (Nnef_BDTPNegotiation, TS 29.554). Authentication of the API consumer is handled separately (see below). These mappings are documented on the Network API Initiatives page.
API consumer authentication
Before any of the calls above, the API consumer authenticates to the operator's authorization server using OAuth 2.0, as defined by the CAMARA Security and Interoperability Profile in the CAMARA IdentityAndConsentManagement repository. CAMARA supports the OAuth 2.0 client credentials grant (for server-to-server, two-legged access) and Client Initiated Backchannel Authentication (CIBA) for flows that require end-user consent; two-legged (client credentials) tokens are restricted to APIs that do not process personal data. The consumer obtains an access token carrying the OAuth scopes for the specific API and operation, then presents it as a bearer token on each call. Credentials themselves are provisioned out of band through the operator's developer portal or Network API Platform; there is no CAMARA API for issuing them.
These identifiers on this page were not confirmed against a primary source (the 3GPP/ETSI portals block automated access): the mapping of specific CAMARA operations to TS 29.522 (Nnef_AFSessionWithQoS, Nnef_BDTPNegotiation), TS 29.514 (Npcf_PolicyAuthorization) and TS 29.554 (Nnef_BDTPNegotiation / BDT policy). Verify against the 3GPP work plan before publication.
Related
- Workflows and Requirements: the requirement categories mapped here.
- Reference Scenarios: the production setups these APIs serve.
- Quality on Demand, QoS Booking, QoS Booking and Assignment, QoS Profiles, Dedicated Networks: the per-API walkthroughs.
- Network API Initiatives: the CAMARA APIs and their 3GPP mappings.
Refer to the Tech repository to contribute to this documentation.