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). For 5G networks the 3GPP specification TS 23.501 defines the Packet Error Rate as a 5G QoS characteristic. (CAMARA QoSProfiles main@8ce8f4d qos-profiles.yaml QosProfile packetErrorLossRate; TS 23.501 V20.3.0 clause 5.7.3.5)
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, Commonalities-conformant), separate from the QualityOnDemand repository that holds Quality on Demand and QoS Provisioning. It is the catalogue that the whole QoS family reads from: a profile is a named, operator-defined bundle of network characteristics, and the other QoS APIs (Quality on Demand, QoS Provisioning, QoS Booking, QoS Booking and Assignment, and the Dedicated Networks profiles) take a profile name as input. The API is read-only: GET /qos-profiles/{name} returns one profile, and POST /retrieve-qos-profiles returns the profiles matching the given criteria (optionally filtered by device, name and status) (CAMARA QoSProfiles main@8ce8f4d qos-profiles.yaml externalDocs url; openapi; /retrieve-qos-profiles POST).

The profile fields resemble the way QoS is characterised inside a 5G Core. A 5G QoS flow is described by a 5G QoS Identifier (5QI) and its associated QoS characteristics: a resource type (guaranteed or non-guaranteed bit rate), a priority level, a Packet Delay Budget and a Packet Error Rate. The CAMARA fields packetDelayBudget and packetErrorLossRate, the targetMin/max upstream and downstream rates and priority are comparable at an application-facing level, but CAMARA leaves the mapping of profiles to connectivity characteristics to agreement between the API provider and the API consumer, and exposes named profiles rather than raw 5QI values.

Two fields are worth calling out for media:

  • l4sQueueType indicates the type of queue the profile uses for L4S (Low Latency, Low Loss, Scalable throughput) traffic management: non-l4s-queue, l4s-queue or mixed-queue. L4S is described in IETF RFC 9330, and the field is marked experimental in the API definition.
  • jitter is defined against ITU Y.1540 and targets the 99th percentile of round-trip delay variation for acknowledged packets.

Known gaps​

The API has no operation to define a profile: profiles are created out of band by the operator. The names of the profiles on offer can be listed with POST /retrieve-qos-profiles, with or without a device filter. Availability is expressed only per country and optionally per network (countryAvailability), with no service-area or time dimension, so a profile's availability at a given place and time is not expressed. 5G-MAG's Self-Assessment below records the remaining points as practical gaps for media workflows (CAMARA QoSProfiles main@8ce8f4d qos-profiles.yaml info.description API functionality; /retrieve-qos-profiles POST description; QosProfile countryAvailability).

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 using the QoS Profiles in the context of Quality on Demand. The following steps are executed:

Sequence showing a QoS Profile being retrieved by name, then used in a Quality on Demand session request.
QoS Profiles in the context of a Quality on Demand request: the profile is looked up by name (Step 1) and the name is then passed to the QoD session.

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 way to list profile names available in the network
  • 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",
    "networkAccessIdentifier": "123456789@domain.com",
    "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):

// Example values: replace with actual network requirements
[
  {
    "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"
  }
]