Skip to main content
Network APIs for Connectivity Quality

Quality on Demand

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: Quality on Demand for Content Production & Contribution​

Find more information about Quality on Demand API.

Purpose​

This API lets a media application request a QoS session for the connection between a device and an application server.

Workflow and Architecture​

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

High-level architecture for Quality on Demand, showing the media application (ASP) invoking the Network API Platform to create a QoS session between a device and an application server.
Entities and interactions for Quality on Demand.

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.

note

Quality on Demand has no separate reservation phase. Unlike the booking-based APIs, the QoS session is created at the point of use (see step 2.1 under "During operation"), at the device's current location; resources cannot be reserved in advance for a future time or area.

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.0a. Discovery of available and eligible QoS Profiles (optional)
2
During operation
ASP
2.1. Request Creation of QoS Session
ASP
2.2. Device establishes connection
ASP
2.3. Usage of API capabilities
3
Dismantling
ASP
3.1a. Deletion of QoS Session
CSP
3.1b. Or the CSP simply tears the QoS session 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​

Details of the already arranged QoS Profile can be retrieved with GET /qos-profiles/{name}, using the QoS Profiles API. For the profile structure and an explanation of the fields, see Using CAMARA APIs: QoS Profiles.

Step 2: During operation​

2.1 Requests creation of QoS session​

With POST /sessions passing the device object, applicationServer IP, applicationServerPorts, devicePorts, qosProfile and duration.

2.2 Device establishes connection​

2.3 Usage of API capabilities​

A series of operations to delete the QoS session or extending its duration are available:

GET /sessions/{sessionId} - Get QoS session information

DELETE /sessions/{sessionId} - Delete a QoS session

POST /sessions/{sessionId}/extend - Extend the duration of an active session

POST /retrieve-sessions - Get QoS session information for a device

Step 3: Dismantling​

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

DELETE /sessions/{sessionId} deletes a QoS session

5G-MAG's Self-Assessment​

  • A session may be created by establishing a level of QoS between the device and the application server for a given duration.
  • It is assumed that the QoD API is invoked with the complete knowledge of device, application server, and at the given location.
  • No information is given to the user on the availability of resources in an area.
  • It is not possible to ensure availability of the QoS session before invoking it at the location, since a service area cannot be defined or requested in advance: whether the request succeeds remains unclear until then.
  • On device failure, the QoS session needs to be deleted with no guarantee that a new one can be created.

Potential improvements:

  • There is no information about the location or service area.
  • Understanding opportunities to book QoS sessions in terms of duration and location/area would be useful as the user may be able to move and find a better coverage spot rather than being denied the establishment of QoS at the time and location in which it is requested.

When to use this API​

Quality on Demand is the point-of-use API: it creates a QoS session at the device's current location, for a device and application server both known at request time, with no advance reservation and no service-area parameter. That makes it the natural fit for short-notice single-device contribution (a journalist arriving at a breaking-news location and starting an uplink there and then), and the counterpart to it, for a device with no fixed session end, is the indefinite QoS Provisioning API.

Because there is no reservation phase, availability is discovered only when POST /sessions is attempted. If the network cannot honour the request at that location, the session is refused; the API gives no prior indication and no alternative area. For a planned event where success needs to be assured ahead of time, an advance, area-scoped reservation API is more appropriate: QoS Booking (device-bound), QoS Booking and Assignment (device count, assign later) or Dedicated Networks (with area discovery). The trade-off between point-of-use and advance reservation is set out on the Using CAMARA APIs page.

Session lifecycle​

A Quality on Demand session has a simple lifecycle that maps onto the "During operation" phase only:

  • Create with POST /sessions, passing the device, applicationServer, applicationServerPorts, devicePorts, qosProfile and duration.
  • Inspect with GET /sessions/{sessionId}, or find sessions for a device with POST /retrieve-sessions.
  • Extend an active session with POST /sessions/{sessionId}/extend, which avoids the gap that deleting and re-creating would introduce.
  • Delete with DELETE /sessions/{sessionId}, or let the operator tear the session down when the duration expires.

The ability to extend a session is a useful feature that the booking APIs do not all offer: an overrunning contribution can keep its QoS without a re-request.

How this maps to 3GPP​

Creating a QoS session drives the Network Exposure Function (NEF) northbound Nnef_AFsessionWithQoS service (TS 29.522); the NEF requests the Policy Control Function to authorise and install the corresponding QoS Flow on the device's PDU session (Npcf_PolicyAuthorization, TS 29.514). Because the session is created at the point of use, no background data transfer negotiation is involved, unlike the advance-reservation APIs. The referenced QoS profile maps to a 5QI whose characteristics are tabulated in TS 23.501 V20.3.0 clause 5.7.4. See Network API Initiatives.