Skip to main content
Network APIs for Connectivity Quality

CAMARA QoS Profiles

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

Description​

The "Quality-of-Service (QoS) Profiles" API exposes a set of predefined network performance characteristics, such as latency, throughput, and priority, each identified by a unique name. These profiles let application developers specify the desired network behaviour for their application's data traffic, so as to ensure optimal performance. By selecting an appropriate QoS profile, developers can request stable latency (reduced jitter) or throughput; what a selected profile is applied to is determined by the API that references it.

A QoS profile is a named, operator-defined bundle of these characteristics. It is the foundational input for most of the other QoS-related APIs: developers usually consult this API first to learn which profile names an operator offers, then pass a chosen name to Quality on Demand, QoS Provisioning, QoS Booking, or Dedicated Networks (CAMARA QoSProfiles main@8ce8f4d qos-profiles.yaml info.description Introduction; CAMARA QualityOnDemand main@471aa35 qos-provisioning.yaml info.description).

Used in the context of:

Information: QoS Profiles project page and GitHub repository (CAMARA QoSProfiles main@8ce8f4d qos-profiles.yaml externalDocs url)

The API definitions can be obtained here: QoSProfiles API_definitions folder (CAMARA QoSProfiles main@8ce8f4d qos-profiles.yaml externalDocs url)

The QoS Profiles API definition (YAML) is available at: qos-profiles.yaml (CAMARA QoSProfiles main@8ce8f4d qos-profiles.yaml externalDocs url)

Operations and dependencies​

QoS Profiles API​

  • POST /retrieve-qos-profiles with a request body that may include a device object, name of the profile and status, it is used to query the QoS Profiles matching these criteria (those available to the device when device is given). The response contains information about the QoS Profiles (CAMARA QoSProfiles main@8ce8f4d qos-profiles.yaml /retrieve-qos-profiles POST retrieveQosProfiles, QosProfileDeviceRequest)
  • GET /qos-profiles/{name} - get QoS Profile for a given name (CAMARA QoSProfiles main@8ce8f4d qos-profiles.yaml /qos-profiles/{name} GET getQosProfile)

Parameters describing a QoS Profile​

ParameterDescription
packetDelayBudgetthe 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 QosProfile packetDelayBudget)
targetMinDownstreamRatethe target minimum downstream rate. (CAMARA QoSProfiles main@8ce8f4d qos-profiles.yaml QosProfile targetMinDownstreamRate)
targetMinUpstreamRatethe target minimum upstream rate (CAMARA QoSProfiles main@8ce8f4d qos-profiles.yaml QosProfile targetMinUpstreamRate)
packetErrorLossRatethe exponential power of the allowable error loss rate 10^(-N). (CAMARA QoSProfiles main@8ce8f4d qos-profiles.yaml QosProfile packetErrorLossRate)
jitterthis 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 QosProfile jitter)
minDurationthe minimum time a session using this profile can be requested for. (CAMARA QoSProfiles main@8ce8f4d qos-profiles.yaml QosProfile minDuration)
maxDurationthe maximum time a session using this profile can be requested for. (CAMARA QoSProfiles main@8ce8f4d qos-profiles.yaml QosProfile maxDuration)
prioritythe relative precedence of this profile when the network arbitrates between competing flows (lower value means higher priority). (CAMARA QoSProfiles main@8ce8f4d qos-profiles.yaml QosProfile priority)
l4sQueueTypewhether the profile uses a Low Latency, Low Loss, Scalable throughput (L4S) queue, an IETF congestion-control scheme designed to keep latency low under load. Example values include non-l4s-queue. (CAMARA QoSProfiles main@8ce8f4d qos-profiles.yaml QosProfile l4sQueueType)

The response example below also carries fields not listed here (for example maxUpstreamRate, maxDownstreamBurstRate, serviceClass). The authoritative field set and allowed values are defined in the qos-profiles.yaml. The full object also includes countryAvailability (the countries in which the profile is offered). The serviceClass field carries a coarse traffic category (for example real_time_interactive) (CAMARA QoSProfiles main@8ce8f4d qos-profiles.yaml QosProfile; externalDocs url).

Standardisation context​

QoS Profiles is defined in the CAMARA QoSProfiles repository (OpenAPI 3.0.3). It is the read-only catalogue the QoS family reads from: a profile is a named, operator-defined bundle of network characteristics, and Quality on Demand, QoS Provisioning, QoS Booking, QoS Booking and Assignment and the Dedicated Networks profiles take its name. GET /qos-profiles/{name} returns one profile; POST /retrieve-qos-profiles returns those matching device, name and status.

Each profile carries delay budget, error rate, rates and priority; what a name delivers is agreed between the API provider and the consumer. For media, l4sQueueType (experimental) selects the L4S queue type, and jitter follows ITU Y.1540 (99th percentile).

Known gaps​

Profiles are created out of band by the operator; the API cannot define one. Availability is expressed per country and optionally per network (countryAvailability), with no service-area or time dimension. The Self-Assessment lists the remaining gaps.


Workflow: Media application retrieving QoS profiles​

A user of a media application would like to retrieve QoS profiles available in the network. An example figure is shown for the Quality on Demand API, which consumes a QoS profile name. The following steps are executed:

Architecture drawing: a planning tool at the field location invokes the Quality on Demand API through a Network API Platform linked to the mobile network; a booking tool at the production centre is also an API consumer. The QoS session applies to the segment between the 5G-enabled production devices and the mobile network, to which devices can be attached with POST /sessions.
The Quality on Demand API is invoked by an API consumer through the Network API Platform. The QoS session applies to the segment between the devices and the mobile network, to which devices can be attached with POST /sessions (figure text). The profile names come from the QoS Profiles API (described in the steps below).

Step 0: Pre-conditions​

  • The API invoker needs to have signed up with the API provider (CAMARA QoSProfiles main@8ce8f4d qos-profiles.yaml info.description Authorization and authentication; CAMARA QoSBooking main@4de93f1 qos-booking.yaml info.description).
  • qosProfiles have already been defined and made available by the network operator. (This API has no operation to define profiles; see the Self-Assessment below, which flags this as a gap.) (CAMARA QoSProfiles main@8ce8f4d qos-profiles.yaml info.description Introduction; paths)
  • Names of such qosProfiles have been disclosed to the user so they can be used when invoking APIs (CAMARA QoSProfiles main@8ce8f4d qos-profiles.yaml info.description Introduction; CAMARA QoSBooking main@4de93f1 qos-booking.yaml info.description QoS profiles term).

Step 1: Check details of an existing QoS Profile (when not cached)​

  • GET /qos-profiles/{name} to obtain the parameters of the QoS Profile (CAMARA QoSProfiles main@8ce8f4d qos-profiles.yaml /qos-profiles/{name} GET getQosProfile)

5G-MAG's Self-Assessment​

The QoS Profiles API would be used prior to the start of the event in order to understand the profiles and details of the profiles available in the network. POST /retrieve-qos-profiles returns the profiles with their parameters, optionally filtered by device, name and status. There is no method to define QoS Profiles, and this operation should be done beforehand (CAMARA QoSProfiles main@8ce8f4d qos-profiles.yaml /retrieve-qos-profiles POST description; info.description API functionality).

Potential improvements:

  • A solution to the fact that QoS Profiles need to be established manually before being able to invoke them.
  • Availability is expressed only per country and network (countryAvailability), not per location or service area. It would be impractical if QoS Profiles would only be retrievable once in the exact location and at a given time.

Quality-of-Service (QoS) Profiles API Usage​

Obtain QoS profiles available​

With POST /retrieve-qos-profiles, and optional device parameters. The request can scope the query to a device, a profile name and a status (CAMARA QoSProfiles main@8ce8f4d qos-profiles.yaml /retrieve-qos-profiles POST QosProfileDeviceRequest):

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

Type of response: information about the QoS Profiles, returned as an array of profile objects. Each object carries the profile name, description, status and its performance characteristics (rates, delay, jitter, priority, and so on) (CAMARA QoSProfiles main@8ce8f4d qos-profiles.yaml /retrieve-qos-profiles POST 200; QosProfile; RateUnitEnum). The values are examples only; they stand for the actual network values:

[
{
"name": "voice",
"description": "QoS profile for voice calls",
"status": "ACTIVE",
"targetMinUpstreamRate": {
"value": 128,
"unit": "kbps"
},
"maxUpstreamRate": {
"value": 128,
"unit": "kbps"
},
"maxUpstreamBurstRate": {
"value": 128,
"unit": "kbps"
},
"targetMinDownstreamRate": {
"value": 128,
"unit": "kbps"
},
"maxDownstreamRate": {
"value": 128,
"unit": "kbps"
},
"maxDownstreamBurstRate": {
"value": 128,
"unit": "kbps"
},
"minDuration": {
"value": 60,
"unit": "Seconds"
},
"maxDuration": {
"value": 60,
"unit": "Seconds"
},
"priority": 20,
"packetDelayBudget": {
"value": 100,
"unit": "Milliseconds"
},
"jitter": {
"value": 30,
"unit": "Milliseconds"
},
"packetErrorLossRate": 3,
"l4sQueueType": "non-l4s-queue",
"serviceClass": "real_time_interactive"
}
]