Skip to main content
Connectivity Quality with Network APIs

QoS Booking and Assignment

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

Using CAMARA APIs: QoS Booking and Assignment for Content Production & Contribution​

Find more information about QoS Booking and Assignment API.

Purpose​

A media application can reserve a QoS Profile for a given period of time and service area, then assign it to devices as they become available.

How this differs from QoS Booking

This API separates the booking of resources from the device assignment: you create a booking for a number of devices first, then attach or detach specific devices to it later. This adds flexibility when the exact devices are not known at booking time or may change during operation. The plain QoS Booking API instead ties the booking to a device (and application server) at creation time. See that page for the contrast.

Workflow and Architecture​

This is a high-level figure with the entities involving APIs and the devices involved:

Diagram forthcoming

An architecture diagram showing the media application (ASP) invoking the Network API Platform to create a booking and assign devices will be added here.

General Workflow​

In the procedure flow below, each step is tagged with the actor that performs it: ASP (Application Service Provider, the media application side) or CSP (Communication Service Provider, the network operator side). Coloured bands group the steps into the phases Pre-conditions, Before using the network, During operation, and Dismantling.

0
Pre-conditions
ASP
+
CSP
On-boarding of the ASP and Negotiation
-  Sign up and access credentials
-  Selection / Request for QoS Profiles
1
Before using the network
ASP
1.0. Discovery of available and eligible QoS Profiles (optional)
ASP
1.1. Request of Creation of QoS Booking
CSP
1.2. Assessment of QoS Booking reservation and change of status
ASP
1.3. Request of Device Assignment for the QoS Booking
2
During operation
CSP
2.1. QoS Booking is activated
ASP
2.2. Device establishes connection
ASP
2.3. Usage of API capabilities
3
Dismantling
ASP
3.1a. Release of Device Assignment and Deletion of QoS Booking
CSP
3.1b. Or the CSP simply tears the QoS Booking down

Step 0: Pre-conditions​

  • The API invoker needs to have signed up with the API provider.
  • qosProfiles have already been defined and made available by the network operator.
  • Names of such qosProfiles have been disclosed to the user so they can be used when invoking APIs.

Step 1: Before using the network​

The step numbers here follow the procedure flow above.

Details of the already arranged QoS Profile can be retrieved with GET /qos-profiles/{name}, using the QoS Profiles API.

1.1 Requests creation of QoS Booking for a given number of devices​

With POST /qos-bookings passing the numDevices, qosProfile, startTime, duration, serviceArea.

1.3 Assign the QoS Booking to a specific Device​

POST /qos-bookings/{bookingId}/devices/assign passing the BookingId from the previous step and a device object to assign the QoS Booking to a specific device.

Step 2: During operation​

2.1 QoS Booking is activated​

The booking becomes active for the assigned devices over the reserved area and time window.

2.2 Device establishes connection​

An assigned device connects to the network and starts using the reserved resources.

2.3 Usage of API capabilities​

A series of operations to manage assignments and delete the QoS Booking are available at runtime; the full endpoint list is given in the reference below.

Endpoint reference​

QoS Booking and Assignment - QoS Booking API​

  • POST /qos-bookings with a request body containing numDevices, qosProfile, startTime, duration, serviceArea, it triggers a new booking in advance and assign this reserved booking profile to one or more devices when the devices are ready. The response includes a bookingId.
    • Dependency: Requires qosProfile which can be retrieved from a previous call to the QoS Profiles API.
  • GET /qos-bookings/{bookingId} - gets booking information for the given bookingId
  • DELETE /qos-bookings/{bookingId} - Cancel an existing booking and release resources related to that booking.

QoS Booking and Assignment - Device Assignment API​

  • POST /qos-bookings/{bookingId}/devices/assign with a request body containing device object, allows the end user to assign one or more devices to the existing QoS Booking.
  • GET /qos-bookings/{bookingId}/devices - allows the end user to retrieve the list of devices assigned to the existing QoS Booking.
  • POST /qos-bookings/{bookingId}/devices/release with a request body containing device object - Release one or more already assigned devices. This is a synchronous call.
  • POST /qos-bookings/retrieve with a request body containing device object - Querying for QoS Booking resource information details for a device. Returns the QoS booking information for a given device. A device may have multiple bookings (for several times and locations), thus the response is an array

Step 3: Dismantling​

When reaching the duration the QoS Booking may be torn down. A graceful way of tearing down will delete the QoS Booking by id.

DELETE /qos-bookings/{bookingId} deletes the QoS Booking

5G-MAG's Self-Assessment​

  • QoS Booking can be invoked before the actual usage of the network starts to ensure that the requested capabilities are "reserved" for the specific area, time window and a given number of devices.
  • Before or during the event a device will be assigned access to the QoS booking.

Potential improvements:

  • Unlike other similar APIs there is no information about the application server. It is unclear what would be the endpoint to which throughput, jitter, latency and other parameters would apply.
  • The procedure is very similar to Dedicated Networks. There seems to be redundancy with QoS Booking
  • This API's internal name, "QoS Booking", is easily confused with the separate, similarly-named QoS Booking API.

When to use this API​

This API is the right choice when resources must be reserved before the exact devices are known, or when devices may change during operation. That describes most planned multi-device productions:

  • A crew books capacity for N cameras for a venue and a time window (POST /qos-bookings with numDevices), before knowing which physical units will be deployed.
  • On site, each camera's SIM is attached to the booking (POST /qos-bookings/{bookingId}/devices/assign) as it comes online.
  • If a camera fails, its device is released (POST /qos-bookings/{bookingId}/devices/release) and a back-up is assigned, all against the same booking, so the reservation is never lost.
  • The on-air / preview / standby prioritisation in the Workflows page is realised by assigning and releasing devices across bookings that carry different QoS profiles, without re-reserving.

For a single, known contribution feed where the device and application server are fixed at booking time, the device-bound QoS Booking API is simpler; for a full venue deployment with area discovery, Dedicated Networks is more complete. This API sits between the two.

Contrast with the device-bound QoS Booking API​

The overlap between this API and the QoS Booking API is real and is noted in the self-assessment above. The essential difference is the point at which a device is bound:

QoS BookingQoS Booking and Assignment
Device bound atcreation (POST /device-qos-bookings)assignment, after creation (POST /qos-bookings/{id}/devices/assign)
Application server in requestyes (applicationServer, ports)no (a noted gap)
Device swapdelete and re-create the bookingrelease and assign against the same booking
Suitsone known feeda set of devices, some interchangeable

How this maps to 3GPP​

A QoS booking reserves per-device QoS treatment that, on assignment and connection, is realised as a QoS Flow on the device's PDU session. The reservation and assignment requests drive the Network Exposure Function (NEF) northbound APIs (TS 29.522); advance reservation of a future window uses background data transfer negotiation (Nnef_BDTPNegotiation, TS 29.554), and the per-device QoS is authorised by the Policy Control Function (Npcf_PolicyAuthorization, TS 29.514). The QoS profile referenced maps to a 5QI whose characteristics are tabulated in TS 23.501, clause 5.7.4. See Network API Initiatives.

References to verify

These identifiers on this page were not confirmed against a primary source (the 3GPP/ETSI portals block automated access): the exact NEF/PCF operations a QoS booking maps to (Nnef_BDTPNegotiation in TS 29.554, Npcf_PolicyAuthorization in TS 29.514, NEF northbound in TS 29.522). Verify against the 3GPP work plan and the current CAMARA QoSBooking specification before publication.

note

Refer to the Tech repository to contribute to this documentation.