CAMARA QoS Provisioning

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

CAMARA: QoS Provisioning API

Description

Developers use the "Quality of Service (QoS) Provisioning" API to request the assignment of a given QoS profile to a specific device, indefinitely. This API sets up the configuration in the network so that the requested QoS profile is applied to the specified device whenever it is connected to the network, until the provisioning is deleted.

How this compares to the other QoS APIs (all of which use a profile from the QoS Profiles API):

QoS Provisioning (this API): persistent. The profile applies to the device every time it connects, until the provisioning is deleted.
Quality on Demand: per session. The profile applies for a requested duration only.
QoS Booking: reserved in advance. Capacity is booked for a future time and area.

Information: QoS Provisioning project page and GitHub repository

The API definitions can be obtained here: QualityOnDemand API_definitions folder

The QoS Provisioning API definition (YAML) is available at: qos-provisioning.yaml

Operations and dependencies

QoS Provisioning API

POST /qos-assignments with the request body including a device object and qosProfile, this request will assign a QoS profile to a device. The response includes an assignmentId.
- Dependency: Requires qosProfiles which can be retrieved from a previous call to the QoS Profiles API.
GET /qos-assignments/{assignmentId} - Querying for details about the QoS profile assignment
DELETE /qos-assignments/{assignmentId} - Revokes the assignment of a QoS profile to a device performed by a previous assignment operation.
POST /retrieve-qos-assignment with the request body including the device object, this request will return information about the QoS profile assignment for the device with an assignmentId.

Standardisation context

QoS Provisioning is defined in the CAMARA QualityOnDemand repository (OpenAPI 3.0.3, Commonalities-conformant), and its repository/landing name is QoD Provisioning. It consumes a named profile from the QoS Profiles API and, when active, maps to the same 5G Core machinery as the rest of the QoS family: the NEF AsSessionWithQoS operation (TS 29.522) driving Npcf_PolicyAuthorization on the PCF (TS 29.514).

The distinguishing property is persistence. Where Quality on Demand applies a profile for a bounded session duration, QoS Provisioning creates an assignment (POST /qos-assignments) that applies the profile to the device every time it connects, until the assignment is deleted (DELETE /qos-assignments/{assignmentId}). GET /qos-assignments/{assignmentId} reads the assignment and POST /retrieve-qos-assignment looks it up by device. The returned status (for example AVAILABLE) reflects whether the network is currently able to honour the assignment.

Comparison within the QoS family

API	Duration	Bound to	Typical media use
QoS Provisioning (this API)	Persistent, until deleted	A specific device	A fixed contribution device that should always get its profile.
Quality on Demand	One session (`duration`)	A device flow	A boost for the length of a live feed.
QoS Booking	A future window	Specific device(s)	Capacity secured ahead of a scheduled event.
QoS Booking and Assignment	A future window	A device count, assigned later	An event where devices are only known on the day.

A practical limitation for media, recorded in the Self-Assessment below, is that the assignment cannot be re-pointed to a different device: replacing a device means deleting the assignment and creating a new one, with no guarantee the new assignment succeeds. There is also no service-area dimension.

Workflow: Media application using the QoS Provisioning API to assign a QoS profile to a device

A user of a media application would like to request the assignment of a QoS Profile to a device. An example figure is shown using the QoS Provisioning in the context of Quality on Demand. The following steps are executed:

QoS Provisioning shown in the Quality on Demand context: the profile is looked up by name, then attached to the device so it applies on every connection.

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: Check details of an existing QoS Profile (when not cached)

GET /qos-profiles/{name} to obtain the parameters of the QoS Profile

Step 2: Attach a device to the QoS Profile

POST /qos-assignments passing the device object and the name of the qosProfile
The received "assignmentId" could be used to query details or revoke the assignment
This QoS profile will be assigned to the device anytime it is connected to the network.

5G-MAG's Self-Assessment

This section records 5G-MAG's practical reading of the API and the open points it raises for media use.

This API would allow attaching a QoS Profile to a device any time it is connected to the network. There is an issue as it is not possible to assign a different device to the existing QoS assignment. If a device would need to be replaced during operation, the existing QoS assignment would have to be deleted and a new assignment created. While doing so there is no guarantee that such new assignment is possible.

Potential improvements:

Ability to update the device to which the QoS Profile applies.
There is no information about the location or service area.
Understanding opportunities 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.

Quality-on-Demand (QoD) Provisioning API Usage

Obtaining the QoS assignment for a device

With POST /retrieve-qos-assignment, and device object. The request identifies the device whose assignment is queried:

{
  "device": {
    "phoneNumber": "+123456789",
    "networkAccessIdentifier": "123456789@domain.com",
    "ipv4Address": {
      "publicAddress": "203.0.113.0",
      "publicPort": 59765
    },
    "ipv6Address": "2001:db8:85a3:8d3:1319:8a2e:370:7344"
  }
}

Type of response: the assignment details, including the assigned qosProfile, the assignmentId (used to query or revoke it) and its current status:

{
  "device": {
    "phoneNumber": "+123456789"
  },
  "qosProfile": "QOS_L",
  "sink": "https://application-server.com/callback",
  "sinkCredential": {
    "credentialType": "ACCESSTOKEN",
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
    "accessTokenExpiresUtc": "2024-12-01T12:00:00Z",
    "accessTokenType": "bearer"
  },
  "assignmentId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "startedAt": "2024-05-12T17:32:01Z",
  "status": "AVAILABLE"
}