QoD for enhanced communication

The Quality-On-Demand (QoD) API provides programmable interface for developers and other users (capabilities consumers) to request stable latency or throughput managed by Telco networks without the necessity to have an in-depth knowledge of the 4G/5G system or the overall complexity of the Telecom Systems.

Introduction

Industrial (IoT), VR/Gaming, live video streaming, autonomous driving and many other scenarios demand network communication quality and are sensitive to any change in transmission conditions. Being able to request a stable latency (reduced jitter) or prioritized throughput from the network can improve user experience substantially.

The QoD API offers the application developers the capability to request for stable latency (reduced jitter) or throughput for some specified application data flows between application clients (within a user device) and Application Servers (backend services). The developer has a pre-defined set of Quality of Service (QoS) profiles which they could choose from depending on their latency or throughput requirements.

The usage of the API is based on QoS session resources, which can be created (based on available QoS profiles), queried and deleted. The deletion of a requested session can be triggered by the API consumer or can be triggered automatically. The automatic process is triggered either when the requested specified duration of a QoS session has reached its limit or the default session expiration time has been reached (within an example provider implementation it is set to 24hrs).

Please note: to use the Device Status API, you must register your interest here.

Relevant terms and definitions

QOD service endpoint: The URL pointing to the RESTful resource of the QoD API.
Authentication: Security access keys such as OAuth 2.0 client credentials used by client applications to invoke the QoD API.
QoS profiles and QoS profile labels: Latency or throughput requirements of the application mapped to relevant QoS profile class.
Identifier for the device: At least one identifier for the device (user equipment) out of four options: IPv4 address, IPv6 address, Phone number, or Network Access Identifier [5] assigned by the mobile network operator for the device.
Identifier for the application server: IPv4 and/or IPv6 address of the application server (application backend)
App-Flow (between the application client and application server): The precise application data flow the developer wants to prioritize and have stable latency or throughput for. This flow is in the current API version determined by the identifiers used for the device and the application server. And it can be further elaborated with details such as ports or port-ranges. Future version of the API might allow more detailed flow identification features.
Duration: Duration (in seconds) for which the QoS session (between application client and application server) should be created. This parameter is optional. When not specified, a default session duration (e.g. 24 hours) is applied. The user may request a termination before its expiration.
Notification URL and token: Developers may provide a callback URL on which notifications about all status change events of the session (eg. session termination) can be received from the service provider. This is an optional parameter.

API functionality

The usage of the QoD API is based on QoS profile classes and parameters which define App-Flows. Based on the API, QoS session resources can be created, queried, and deleted. Once an offered QoS profile class is requested, application users get a prioritized service with stable latency or throughput even in the case of congestion. The QoD API has the following characteristics:

A specified App-Flow is prioritized to ensure stable latency or throughput for that flow.
The prioritized App-Flow is described by providing information such as device IP address (or other device identifier) & application server IP addresses and port/port-ranges.
The developer can optionally specify the duration for which they need the prioritized App-flow.
Stable latency or throughput is requested by selecting from the list of QoS profiles made available by the service provider (e.g. QOS_E) to map latency and throughput requirements.
The developer can optionally also specify callback URL on which notifications for the session can be sent.

Following diagram shows the interaction between different components

How QoS profiles are mapped to connectivity characteristics are subject to agreements between the communication service provider and the API invoker. Within the CAMARA project, you can find a sample for such a mapping of QoS profiles. CAMARA QoS Profiles Mapping Table (REFERENCE DRAFT)

Further info and support

(FAQs will be added in a later version of the documentation)

Download OpenAPI Specification

QoS Sessions

Manage QoS sessions

Available Operations

Creates a new session

Create QoS Session to manage latency/throughput priorities

If the qosStatus in the API response is "AVAILABLE" and a notification callback is provided the client will receive in addition to the response a QOS_STATUS_CHANGED event notification with qosStatus as AVAILABLE.

If the qosStatus in the API response is REQUESTED, the client will receive either

a QOS_STATUS_CHANGED event notification with qosStatus as AVAILABLE after the network notifies that it has created the requested session, or
a QOS_STATUS_CHANGED event notification with qosStatus as UNAVAILABLE and statusInfo as NETWORK_TERMINATED after the network notifies that it has failed to provide the requested session.

A QOS_STATUS_CHANGED event notification with qosStatus as UNAVAILABLE will also be send if the network terminates the session before the requested duration expired

NOTE: in case of a QOS_STATUS_CHANGED event with qosStatus as UNAVAILABLE and statusInfo as NETWORK_TERMINATED the resources of the QoS session are not directly released, but will get deleted automatically at earliest 360 seconds after the event. This behavior allows clients which are not receiving notification events but are polling to get the session information with the qosStatus UNAVAILABLE and statusInfo NETWORK_TERMINATED. Before a client can attempt to create a new QoD session for the same device and flow period they must release the session resources with an explicit delete operation if not yet automatically deleted.

post{apiRoot}/camara/qod/v0100/sessions

Server Variables

Variable	Description	Default Value	Options
apiRoot	API root, defined by the service provider, e.g. `api.example.com` or `api.example.com/somepath`	https://api-eu.vonage.com

Authentication

Key	Description	Where	Example
openId	Read more

Request Body
Content Type
application/json

duration

integer(int32)

Min1

Max86400

Default86400

example86400

Session duration in seconds. Maximal value of 24 hours is used if not set. After session is expired the, client will receive a QOS_STATUS_CHANGED event with

qosStatus as UNAVAILABLE, and,
statusInfo as DURATION_EXPIRED. See notification callback.

device

object

Required

End-user equipment able to connect to a mobile network. Examples of devices include smartphones or IoT sensors/actuators.

The developer can choose to provide the below specified device identifiers:

ipv6Address
phoneNumber

NOTE: the MNO might support only a subset of these options. The API invoker can provide multiple identifiers to be compatible across different MNOs. In this case the identifiers MUST belong to the same device

phoneNumber

string

example123456789

A public identifier addressing a telephone subscription. In mobile networks it corresponds to the MSISDN (Mobile Station International Subscriber Directory Number). In order to be globally unique it has to be formatted in international format, according to E.164 standard, optionally prefixed with '+'.

ipv6Address

string(ipv6)

example2001:db8:85a3:8d3:1319:8a2e:370:7344

The device should be identified by the observed IPv6 address, or by any single IPv6 address from within the subnet allocated to the device (e.g. adding ::0 to the /64 prefix).

The session shall apply to all IP flows between the device subnet and the specified application server, unless further restricted by the optional parameters devicePorts or applicationServerPorts.

applicationServer

object

Required

A server hosting backend applications to deliver some business logic to clients.

The developer can choose to provide the below specified device identifiers:

ipv6Address

ipv6Address

string

example2001:db8:85a3:8d3:1319:8a2e:370:7344

IPv6 address may be specified in form <address/mask> as:

address - The /128 subnet is optional for single addresses:
- 2001:db8:85a3:8d3:1319:8a2e:370:7344
- 2001:db8:85a3:8d3:1319:8a2e:370:7344/128
address/mask - an IP v6 number with a mask:
- 2001:db8:85a3:8d3::0/64
- 2001:db8:85a3:8d3::/64

devicePorts

object

The ports used locally by the device for flows to which the requested QoS profile should apply. If omitted, then the qosProfile will apply to all flows between the device and the specified application server address and ports

ranges

array

from

integer

Required

Max65535

TCP or UDP port number

integer

Required

Max65535

TCP or UDP port number

ports

array

applicationServerPorts

object

A list of single ports or port ranges on the application server

ranges

array

from

integer

Required

Max65535

TCP or UDP port number

integer

Required

Max65535

TCP or UDP port number

ports

array

qosProfile

string(string)

Required

Min3

Max256

exampleQCI_1_voice

A unique name for identifying a specific QoS profile. This may follow different formats depending on the service providers implementation. Some options addresses:

A UUID style string
Support for the predefined profile QOS_L
A searchable descriptive name

webhook

object

notificationUrl

string(uri)

Required

examplehttps://application-server.com

Allows asynchronous delivery of session related events

notificationAuthToken

string

Min20

Max256

examplec8974e592c2fa383d4a3960714

Authentication token for callback API

Example Request

{
   "duration": 86400,
   "device": {
      "phoneNumber": "123456789",
      "ipv6Address": "2001:db8:85a3:8d3:1319:8a2e:370:7344"
   },
   "applicationServer": {
      "ipv6Address": "2001:db8:85a3:8d3:1319:8a2e:370:7344"
   },
   "devicePorts": {
      "ranges": [
         {
            "from": 5010,
            "to": 5020
         }
      ],
      "ports": [
         5060,
         5070
      ]
   },
   "applicationServerPorts": {
      "ranges": [
         {
            "from": 5010,
            "to": 5020
         }
      ],
      "ports": [
         5060,
         5070
      ]
   },
   "qosProfile": "QCI_1_voice",
   "webhook": {
      "notificationUrl": "https://application-server.com",
      "notificationAuthToken": "c8974e592c2fa383d4a3960714"
   }
}

{
   "duration": 86400,
   "device": {
      "phoneNumber": "123456789",
      "ipv6Address": "2001:db8:85a3:8d3:1319:8a2e:370:7344"
   },
   "applicationServer": {
      "ipv6Address": "2001:db8:85a3:8d3:1319:8a2e:370:7344"
   },
   "devicePorts": {
      "ranges": [
         {
            "from": 5010,
            "to": 5020
         }
      ],
      "ports": [
         5060,
         5070
      ]
   },
   "applicationServerPorts": {
      "ranges": [
         {
            "from": 5010,
            "to": 5020
         }
      ],
      "ports": [
         5060,
         5070
      ]
   },
   "qosProfile": "QCI_1_voice",
   "webhook": {
      "notificationUrl": "https://application-server.com",
      "notificationAuthToken": "c8974e592c2fa383d4a3960714"
   }
}

Responses
Content Type
application/json

Session created

duration

integer(int32)

Required

Min1

Max86400

Default86400

example86400

Session duration in seconds. Maximal value of 24 hours is used if not set. After session is expired the, client will receive a QOS_STATUS_CHANGED event with

qosStatus as UNAVAILABLE, and,
statusInfo as DURATION_EXPIRED. See notification callback.

device

object

Required

End-user equipment able to connect to a mobile network. Examples of devices include smartphones or IoT sensors/actuators.

The developer can choose to provide the below specified device identifiers:

ipv6Address
phoneNumber

phoneNumber

string

example123456789

ipv6Address

string(ipv6)

example2001:db8:85a3:8d3:1319:8a2e:370:7344

The device should be identified by the observed IPv6 address, or by any single IPv6 address from within the subnet allocated to the device (e.g. adding ::0 to the /64 prefix).

The session shall apply to all IP flows between the device subnet and the specified application server, unless further restricted by the optional parameters devicePorts or applicationServerPorts.

applicationServer

object

Required

A server hosting backend applications to deliver some business logic to clients.

The developer can choose to provide the below specified device identifiers:

ipv6Address

ipv6Address

string

example2001:db8:85a3:8d3:1319:8a2e:370:7344

IPv6 address may be specified in form <address/mask> as:

address - The /128 subnet is optional for single addresses:
- 2001:db8:85a3:8d3:1319:8a2e:370:7344
- 2001:db8:85a3:8d3:1319:8a2e:370:7344/128
address/mask - an IP v6 number with a mask:
- 2001:db8:85a3:8d3::0/64
- 2001:db8:85a3:8d3::/64

devicePorts

object

ranges

array

from

integer

Required

Max65535

TCP or UDP port number

integer

Required

Max65535

TCP or UDP port number

ports

array

applicationServerPorts

object

A list of single ports or port ranges on the application server

ranges

array

from

integer

Required

Max65535

TCP or UDP port number

integer

Required

Max65535

TCP or UDP port number

ports

array

qosProfile

string(string)

Required

Min3

Max256

exampleQCI_1_voice

A unique name for identifying a specific QoS profile. This may follow different formats depending on the service providers implementation. Some options addresses:

A UUID style string
Support for the predefined profile QOS_L
A searchable descriptive name

webhook

object

notificationUrl

string(uri)

Required

examplehttps://application-server.com

Allows asynchronous delivery of session related events

notificationAuthToken

string

Min20

Max256

examplec8974e592c2fa383d4a3960714

Authentication token for callback API

sessionId

string(uuid)

Required

Session ID in UUID format

startedAt

integer(int64)

Required

example1639479600

Timestamp of session start in seconds since Unix epoch

expiresAt

integer(int64)

Required

example1639566000

Timestamp of session expiration if the session was not deleted, in seconds since Unix epoch

qosStatus

string

Required

The current status of the requested QoS session. The status can be one of the following:

REQUESTED - QoS has been requested by creating a session
AVAILABLE - The requested QoS has been provided by the network
UNAVAILABLE - The requested QoS cannot be provided by the network due to some reason

Must be one of:REQUESTEDAVAILABLEUNAVAILABLE

messages

array

severity

string

Required

Message severity

Must be one of:INFOWARNING

description

string

Required

Detailed message text

Example Response

{
   "duration": 86400,
   "device": {
      "phoneNumber": "123456789",
      "ipv6Address": "2001:db8:85a3:8d3:1319:8a2e:370:7344"
   },
   "applicationServer": {
      "ipv6Address": "2001:db8:85a3:8d3:1319:8a2e:370:7344"
   },
   "devicePorts": {
      "ranges": [
         {
            "from": 5010,
            "to": 5020
         }
      ],
      "ports": [
         5060,
         5070
      ]
   },
   "applicationServerPorts": {
      "ranges": [
         {
            "from": 5010,
            "to": 5020
         }
      ],
      "ports": [
         5060,
         5070
      ]
   },
   "qosProfile": "QCI_1_voice",
   "webhook": {
      "notificationUrl": "https://application-server.com",
      "notificationAuthToken": "c8974e592c2fa383d4a3960714"
   },
   "sessionId": "f6567dd8-e069-418e-8893-7d22fcf12459",
   "startedAt": 1639479600,
   "expiresAt": 1639566000,
   "qosStatus": "REQUESTED",
   "messages": [
      {
         "severity": "INFO",
         "description": "string"
      }
   ]
}

Session notifications callback callback

Important: this endpoint is to be implemented by the API consumer. The QoD server will call this endpoint whenever any QoS session change (e.g. network termination) related event occurs. Currently only QOS_STATUS_CHANGED event is defined.

posthttps://example.com/webhooks/event

Request Body
Content Type
application/cloudevents+json

string

Required

Identifier of this event, that must be unique in the source context.

source

string(uri-reference)

Required

Identifies the context in which an event happened in the specific Provider Implementation.

type

string

Required

The type of the event.

Must be one of:org.camaraproject.qod.v0.qos-status-changed

specversion

string

Required

Version of the specification to which this event conforms (must be 1.0 if it conforms to cloudevents 1.0.2 version)

Must be one of:1.0

datacontenttype

string

media-type that describes the event payload encoding, must be "application/json" for CAMARA APIs

Must be one of:application/json

data

object

Event notification details payload, which depends on the event type

sessionId

string(uuid)

Required

Session ID in UUID format

qosStatus

string

Required

The current status of a requested or previously available session. Applicable values in the event are:

AVAILABLE - The requested QoS has been provided by the network.
UNAVAILABLE - A requested or previously available QoS session is now unavailable. statusInfo may provide additional information about the reason for the unavailability.

Must be one of:AVAILABLEUNAVAILABLE

statusInfo

string

Reason for the new qosStatus. Currently statusInfo is only applicable when qosStatus is 'UNAVAILABLE'.

DURATION_EXPIRED - Session terminated due to requested duration expired
NETWORK_TERMINATED - Network terminated the session before the requested duration expired
DELETE_REQUESTED- User requested the deletion of the session before the requested duration expired

Must be one of:DURATION_EXPIREDNETWORK_TERMINATEDDELETE_REQUESTED

time

string(date-time)

Required

Timestamp of when the occurrence happened. It must follow RFC 3339

Example Payload

{
   "id": "string",
   "source": "../dictionary",
   "type": "org.camaraproject.qod.v0.qos-status-changed",
   "specversion": "1.0",
   "datacontenttype": "application/json",
   "data": {
      "sessionId": "f6567dd8-e069-418e-8893-7d22fcf12459",
      "qosStatus": "AVAILABLE",
      "statusInfo": "DURATION_EXPIRED"
   },
   "time": "2019-08-24T14:15:22Z"
}

Responses

Successful notification

Get QoS session information

Querying for QoS session resource information details

get{apiRoot}/camara/qod/v0100/sessions/:sessionId

Server Variables

Variable	Description	Default Value	Options
apiRoot	API root, defined by the service provider, e.g. `api.example.com` or `api.example.com/somepath`	https://api-eu.vonage.com

Authentication

Key	Description	Where	Example
openId	Read more

Path Parameters

sessionId

string(uuid)

Required

Session ID that was obtained from the createSession operation

Responses
Content Type
application/json

Contains information about active session

duration

integer(int32)

Required

Min1

Max86400

Default86400

example86400

Session duration in seconds. Maximal value of 24 hours is used if not set. After session is expired the, client will receive a QOS_STATUS_CHANGED event with

qosStatus as UNAVAILABLE, and,
statusInfo as DURATION_EXPIRED. See notification callback.

device

object

Required

End-user equipment able to connect to a mobile network. Examples of devices include smartphones or IoT sensors/actuators.

The developer can choose to provide the below specified device identifiers:

ipv6Address
phoneNumber

phoneNumber

string

example123456789

ipv6Address

string(ipv6)

example2001:db8:85a3:8d3:1319:8a2e:370:7344

The device should be identified by the observed IPv6 address, or by any single IPv6 address from within the subnet allocated to the device (e.g. adding ::0 to the /64 prefix).

The session shall apply to all IP flows between the device subnet and the specified application server, unless further restricted by the optional parameters devicePorts or applicationServerPorts.

applicationServer

object

Required

A server hosting backend applications to deliver some business logic to clients.

The developer can choose to provide the below specified device identifiers:

ipv6Address

ipv6Address

string

example2001:db8:85a3:8d3:1319:8a2e:370:7344

IPv6 address may be specified in form <address/mask> as:

address - The /128 subnet is optional for single addresses:
- 2001:db8:85a3:8d3:1319:8a2e:370:7344
- 2001:db8:85a3:8d3:1319:8a2e:370:7344/128
address/mask - an IP v6 number with a mask:
- 2001:db8:85a3:8d3::0/64
- 2001:db8:85a3:8d3::/64

devicePorts

object

ranges

array

from

integer

Required

Max65535

TCP or UDP port number

integer

Required

Max65535

TCP or UDP port number

ports

array

applicationServerPorts

object

A list of single ports or port ranges on the application server

ranges

array

from

integer

Required

Max65535

TCP or UDP port number

integer

Required

Max65535

TCP or UDP port number

ports

array

qosProfile

string(string)

Required

Min3

Max256

exampleQCI_1_voice

A unique name for identifying a specific QoS profile. This may follow different formats depending on the service providers implementation. Some options addresses:

A UUID style string
Support for the predefined profile QOS_L
A searchable descriptive name

webhook

object

notificationUrl

string(uri)

Required

examplehttps://application-server.com

Allows asynchronous delivery of session related events

notificationAuthToken

string

Min20

Max256

examplec8974e592c2fa383d4a3960714

Authentication token for callback API

sessionId

string(uuid)

Required

Session ID in UUID format

startedAt

integer(int64)

Required

example1639479600

Timestamp of session start in seconds since Unix epoch

expiresAt

integer(int64)

Required

example1639566000

Timestamp of session expiration if the session was not deleted, in seconds since Unix epoch

qosStatus

string

Required

The current status of the requested QoS session. The status can be one of the following:

REQUESTED - QoS has been requested by creating a session
AVAILABLE - The requested QoS has been provided by the network
UNAVAILABLE - The requested QoS cannot be provided by the network due to some reason

Must be one of:REQUESTEDAVAILABLEUNAVAILABLE

messages

array

severity

string

Required

Message severity

Must be one of:INFOWARNING

description

string

Required

Detailed message text

Example Response

{
   "duration": 86400,
   "device": {
      "phoneNumber": "123456789",
      "ipv6Address": "2001:db8:85a3:8d3:1319:8a2e:370:7344"
   },
   "applicationServer": {
      "ipv6Address": "2001:db8:85a3:8d3:1319:8a2e:370:7344"
   },
   "devicePorts": {
      "ranges": [
         {
            "from": 5010,
            "to": 5020
         }
      ],
      "ports": [
         5060,
         5070
      ]
   },
   "applicationServerPorts": {
      "ranges": [
         {
            "from": 5010,
            "to": 5020
         }
      ],
      "ports": [
         5060,
         5070
      ]
   },
   "qosProfile": "QCI_1_voice",
   "webhook": {
      "notificationUrl": "https://application-server.com",
      "notificationAuthToken": "c8974e592c2fa383d4a3960714"
   },
   "sessionId": "f6567dd8-e069-418e-8893-7d22fcf12459",
   "startedAt": 1639479600,
   "expiresAt": 1639566000,
   "qosStatus": "REQUESTED",
   "messages": [
      {
         "severity": "INFO",
         "description": "string"
      }
   ]
}

Delete a QoS session

Release resources related to QoS session

If the notification callback is provided and the qosStatus of the session was AVAILABLE the client will receive in addition to the response a QOS_STATUS_CHANGED event with

qosStatus as UNAVAILABLE and
statusInfo as DELETE_REQUESTED There will be no notification event if the qosStatus was already UNAVAILABLE.

delete{apiRoot}/camara/qod/v0100/sessions/:sessionId

Server Variables

Variable	Description	Default Value	Options
apiRoot	API root, defined by the service provider, e.g. `api.example.com` or `api.example.com/somepath`	https://api-eu.vonage.com

Authentication

Key	Description	Where	Example
openId	Read more

Path Parameters

sessionId

string(uuid)

Required

Session ID that was obtained from the createSession operation

Responses

Session deleted

Extend the duration of an active session

Extend the duration of an active QoS session. If this operation is executed successfully, the new duration of the target session will be the original duration plus the additional duration. The remaining duration plus the requested additional duration shall not exceed the maximum limit. Otherwise, the new remaining duration will be the maximum limit.

post{apiRoot}/camara/qod/v0100/sessions/:sessionId/extend

Server Variables

Variable	Description	Default Value	Options
apiRoot	API root, defined by the service provider, e.g. `api.example.com` or `api.example.com/somepath`	https://api-eu.vonage.com

Authentication

Key	Description	Where	Example
openId	Read more

Path Parameters

sessionId

string(uuid)

Required

Session ID that was obtained from the createSession operation

Request Body
Content Type
application/json

requestedAdditionalDuration

integer(int32)

Required

Min1

Max86399

example60

Additional duration in seconds to be extended.

Example Request

{
   "requestedAdditionalDuration": 60
}

{
   "requestedAdditionalDuration": 60
}

Responses
Content Type
application/json

Contains information about active session

duration

integer(int32)

Required

Min1

Max86400

Default86400

example86400

Session duration in seconds. Maximal value of 24 hours is used if not set. After session is expired the, client will receive a QOS_STATUS_CHANGED event with

qosStatus as UNAVAILABLE, and,
statusInfo as DURATION_EXPIRED. See notification callback.

device

object

Required

End-user equipment able to connect to a mobile network. Examples of devices include smartphones or IoT sensors/actuators.

The developer can choose to provide the below specified device identifiers:

ipv6Address
phoneNumber

phoneNumber

string

example123456789

ipv6Address

string(ipv6)

example2001:db8:85a3:8d3:1319:8a2e:370:7344

The device should be identified by the observed IPv6 address, or by any single IPv6 address from within the subnet allocated to the device (e.g. adding ::0 to the /64 prefix).

The session shall apply to all IP flows between the device subnet and the specified application server, unless further restricted by the optional parameters devicePorts or applicationServerPorts.

applicationServer

object

Required

A server hosting backend applications to deliver some business logic to clients.

The developer can choose to provide the below specified device identifiers:

ipv6Address

ipv6Address

string

example2001:db8:85a3:8d3:1319:8a2e:370:7344

IPv6 address may be specified in form <address/mask> as:

address - The /128 subnet is optional for single addresses:
- 2001:db8:85a3:8d3:1319:8a2e:370:7344
- 2001:db8:85a3:8d3:1319:8a2e:370:7344/128
address/mask - an IP v6 number with a mask:
- 2001:db8:85a3:8d3::0/64
- 2001:db8:85a3:8d3::/64

devicePorts

object

ranges

array

from

integer

Required

Max65535

TCP or UDP port number

integer

Required

Max65535

TCP or UDP port number

ports

array

applicationServerPorts

object

A list of single ports or port ranges on the application server

ranges

array

from

integer

Required

Max65535

TCP or UDP port number

integer

Required

Max65535

TCP or UDP port number

ports

array

qosProfile

string(string)

Required

Min3

Max256

exampleQCI_1_voice

A unique name for identifying a specific QoS profile. This may follow different formats depending on the service providers implementation. Some options addresses:

A UUID style string
Support for the predefined profile QOS_L
A searchable descriptive name

webhook

object

notificationUrl

string(uri)

Required

examplehttps://application-server.com

Allows asynchronous delivery of session related events

notificationAuthToken

string

Min20

Max256

examplec8974e592c2fa383d4a3960714

Authentication token for callback API

sessionId

string(uuid)

Required

Session ID in UUID format

startedAt

integer(int64)

Required

example1639479600

Timestamp of session start in seconds since Unix epoch

expiresAt

integer(int64)

Required

example1639566000

Timestamp of session expiration if the session was not deleted, in seconds since Unix epoch

qosStatus

string

Required

The current status of the requested QoS session. The status can be one of the following:

REQUESTED - QoS has been requested by creating a session
AVAILABLE - The requested QoS has been provided by the network
UNAVAILABLE - The requested QoS cannot be provided by the network due to some reason

Must be one of:REQUESTEDAVAILABLEUNAVAILABLE

messages

array

severity

string

Required

Message severity

Must be one of:INFOWARNING

description

string

Required

Detailed message text

Example Response

{
   "duration": 86400,
   "device": {
      "phoneNumber": "123456789",
      "ipv6Address": "2001:db8:85a3:8d3:1319:8a2e:370:7344"
   },
   "applicationServer": {
      "ipv6Address": "2001:db8:85a3:8d3:1319:8a2e:370:7344"
   },
   "devicePorts": {
      "ranges": [
         {
            "from": 5010,
            "to": 5020
         }
      ],
      "ports": [
         5060,
         5070
      ]
   },
   "applicationServerPorts": {
      "ranges": [
         {
            "from": 5010,
            "to": 5020
         }
      ],
      "ports": [
         5060,
         5070
      ]
   },
   "qosProfile": "QCI_1_voice",
   "webhook": {
      "notificationUrl": "https://application-server.com",
      "notificationAuthToken": "c8974e592c2fa383d4a3960714"
   },
   "sessionId": "f6567dd8-e069-418e-8893-7d22fcf12459",
   "startedAt": 1639479600,
   "expiresAt": 1639566000,
   "qosStatus": "REQUESTED",
   "messages": [
      {
         "severity": "INFO",
         "description": "string"
      }
   ]
}

QoS Profiles

Manage QoS Profiles

Available Operations

Get All QoS Profiles

Returns all QoS Profiles that match the given criteria. If no criteria is given, all QoS Profiles are returned.

get{apiRoot}/camara/qod/v0100/qos-profiles

Server Variables

Variable	Description	Default Value	Options
apiRoot	API root, defined by the service provider, e.g. `api.example.com` or `api.example.com/somepath`	https://api-eu.vonage.com

Query Parameters

status

string

Must be one of:ACTIVEINACTIVEDEPRECATED

name

string

QoS Profile name

Responses
Content Type
application/json

Contains information about QoS Profiles

array

name

string(string)

Required

Min3

Max256

exampleQCI_1_voice

A unique name for identifying a specific QoS profile. This may follow different formats depending on the service providers implementation. Some options addresses:

A UUID style string
Support for the predefined profile QOS_L
A searchable descriptive name

description

string

exampleQoS profile for video streaming

A description of the QoS profile.

status

string

Required

The current status of the QoS Profile

ACTIVE- QoS Profile is available to be used
INACTIVE- QoS Profile is not currently available to be deployed
DEPRECATED- QoS profile is actively being used in a QoD session, but can not be deployed in new QoD sessions

Must be one of:ACTIVEINACTIVEDEPRECATED

targetMinUpstreamRate

object

This is the target minimum upstream rate for the QoS profile. For 5G networks 3GPP Guaranteed Bit Rate (GBR) refers to a dedicated, fixed data rate assigned to specific services, ensuring a minimum performance level. As per 3GPP TS 23.203, GBR is a QoS parameter used to manage traffic classes in mobile networks. It provides a stable data rate for latency-sensitive applications, such as voice calls or video streaming, helping maintain a consistent user experience. When this attribute is set this could imply that a GBR QCI is used, though mechanisms on the network can be used to ensure a minimum performance level without using a GBR QCI. The committed data rate allocated to specific services, ensuring a consistent level of performance. For DOCSIS networks, the "Minimum Reserved Traffic Rate" is defined in the DOCSIS 3.1 - MAC and Upper Layer Protocols Interface Specification" and it ensures a consistent level of performance for specific services within the network.

value

integer(int32)

Max1024

example10

unit

string

Must be one of:bpskbpsMbpsGbpsTbps

maxUpstreamRate

object

The maximum best effort data

value

integer(int32)

Max1024

example10

unit

string

Must be one of:bpskbpsMbpsGbpsTbps

maxUpstreamBurstRate

object

When defined, this is the maximum upstream burst rate for the QoS profile, that will enable the network to burst data at a higher rate than the maxUpstreamRate for a period of time.

value

integer(int32)

Max1024

example10

unit

string

Must be one of:bpskbpsMbpsGbpsTbps

targetMinDownstreamRate

object

This is the target minimum downstream rate for the QoS profile. For 5G networks 3GPP Guaranteed Bit Rate (GBR) refers to a dedicated, fixed data rate assigned to specific services, ensuring a minimum performance level. As per 3GPP TS 23.203, GBR is a QoS parameter used to manage traffic classes in mobile networks. It provides a stable data rate for latency-sensitive applications, such as voice calls or video streaming, helping maintain a consistent user experience. When this attribute is set this could imply that a GBR QCI is used, though mechanisms on the network can be used to ensure a minimum performance level without using a GBR QCI. The committed data rate allocated to specific services, ensuring a consistent level of performance. DOCSIS networks, the "Minimum Reserved Traffic Rate" is defined in the DOCSIS 3.1 - MAC and Upper Layer Protocols Interface Specification" and it ensures a consistent level of performance for specific services within the network.

value

integer(int32)

Max1024

example10

unit

string

Must be one of:bpskbpsMbpsGbpsTbps

maxDownstreamRate

object

The maximum best effort rate

value

integer(int32)

Max1024

example10

unit

string

Must be one of:bpskbpsMbpsGbpsTbps

maxDownstreamBurstRate

object

When defined, this is the maximum downstream burst rate for the QoS profile, that will enable the network to burst data at a higher rate than the maxDownstreamRate for a period of time. This can result in improved user experience when there is additional network capacity. For instance, when a user is streaming a video, the network can burst data at a higher rate to fill the buffer, and then return to the maxUpstreamRate once the buffer is full.

value

integer(int32)

Max1024

example10

unit

string

Must be one of:bpskbpsMbpsGbpsTbps

minDuration

object

The shortest time period that this profile can be deployed.

value

integer(int32)

Min1

example12

unit

string

exampleMinutes

Must be one of:DaysHoursMinutesSecondsMillisecondsMicrosecondsNanoseconds

maxDuration

object

The maximum time period that this profile can be deployed. NOTE: currently the duration within sessionInfo is limited to 86400 seconds (1 day). The value of maxDuration shouldn't therefore exceed this time period. The limitation might be removed in later versions.

value

integer(int32)

Min1

example12

unit

string

exampleMinutes

Must be one of:DaysHoursMinutesSecondsMillisecondsMicrosecondsNanoseconds

priority

integer(int32)

Min1

Max100

example20

Priority levels allow efficient resource allocation and ensure optimal performance for various services in each technology, with the highest priority traffic receiving preferential treatment. The lower value the higher priority. Not all access networks use the same priority range, so this priority will be scaled to the access network's priority range.

packetDelayBudget

object

The packet delay budget is the maximum allowable one-way latency between the customer's device and the gateway from the operator's network to other networks. By limiting the delay, the network can provide an acceptable level of performance for various services, such as voice calls, video streaming, and data. The end-to-end or round trip latency will be about two times this value plus the latency not controlled by the operator

value

integer(int32)

Min1

example12

unit

string

exampleMinutes

Must be one of:DaysHoursMinutesSecondsMillisecondsMicrosecondsNanoseconds

jitter

object

The jitter 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). This requirement helps maintain consistent latency, essential for real-time applications such as VoIP, video calls, and gaming.

value

integer(int32)

Min1

example12

unit

string

exampleMinutes

Must be one of:DaysHoursMinutesSecondsMillisecondsMicrosecondsNanoseconds

packetErrorLossRate

integer(int32)

Min1

Max10

example3

The exponential power of the allowable error loss rate 10^(-N). For instance 3 would be an error loss rate of 10 to the power of -3 (0.001)

For 5G network the 3GPP specification TS 23.203 defines the packet error loss rate QCI attribute. It describes the Quality of Service (QoS) Class Identifier (QCI) parameters used to differentiate traffic classes in mobile networks, ensuring appropriate resource allocation and performance for various services.

The packet error loss rate is one of the QCI attributes, providing information on the acceptable packet loss rate for a specific traffic class. This attribute helps maintain the desired performance level for services like voice calls, video streaming, or data transfers within the 3GPP mobile network.

Example Response

[
   {
      "name": "QCI_1_voice",
      "description": "QoS profile for video streaming",
      "status": "ACTIVE",
      "targetMinUpstreamRate": {
         "value": 10,
         "unit": "bps"
      },
      "maxUpstreamRate": {
         "value": 10,
         "unit": "bps"
      },
      "maxUpstreamBurstRate": {
         "value": 10,
         "unit": "bps"
      },
      "targetMinDownstreamRate": {
         "value": 10,
         "unit": "bps"
      },
      "maxDownstreamRate": {
         "value": 10,
         "unit": "bps"
      },
      "maxDownstreamBurstRate": {
         "value": 10,
         "unit": "bps"
      },
      "minDuration": {
         "value": 12,
         "unit": "Minutes"
      },
      "maxDuration": {
         "value": 12,
         "unit": "Minutes"
      },
      "priority": 20,
      "packetDelayBudget": {
         "value": 12,
         "unit": "Minutes"
      },
      "jitter": {
         "value": 12,
         "unit": "Minutes"
      },
      "packetErrorLossRate": 3
   }
]

Get QoS Profile for a given name

Returns a QoS Profile that matches the given name.

get{apiRoot}/camara/qod/v0100/qos-profiles/:name

Server Variables

Variable	Description	Default Value	Options
apiRoot	API root, defined by the service provider, e.g. `api.example.com` or `api.example.com/somepath`	https://api-eu.vonage.com

Path Parameters

name

string(string)

Required

Min3

Max256

exampleQCI_1_voice

Responses
Content Type
application/json

Contains information about QoS Profiles

name

string(string)

Required

Min3

Max256

exampleQCI_1_voice

A unique name for identifying a specific QoS profile. This may follow different formats depending on the service providers implementation. Some options addresses:

A UUID style string
Support for the predefined profile QOS_L
A searchable descriptive name

description

string

exampleQoS profile for video streaming

A description of the QoS profile.

status

string

Required

The current status of the QoS Profile

ACTIVE- QoS Profile is available to be used
INACTIVE- QoS Profile is not currently available to be deployed
DEPRECATED- QoS profile is actively being used in a QoD session, but can not be deployed in new QoD sessions

Must be one of:ACTIVEINACTIVEDEPRECATED

targetMinUpstreamRate

object

value

integer(int32)

Max1024

example10

unit

string

Must be one of:bpskbpsMbpsGbpsTbps

maxUpstreamRate

object

The maximum best effort data

value

integer(int32)

Max1024

example10

unit

string

Must be one of:bpskbpsMbpsGbpsTbps

maxUpstreamBurstRate

object

When defined, this is the maximum upstream burst rate for the QoS profile, that will enable the network to burst data at a higher rate than the maxUpstreamRate for a period of time.

value

integer(int32)

Max1024

example10

unit

string

Must be one of:bpskbpsMbpsGbpsTbps

targetMinDownstreamRate

object

value

integer(int32)

Max1024

example10

unit

string

Must be one of:bpskbpsMbpsGbpsTbps

maxDownstreamRate

object

The maximum best effort rate

value

integer(int32)

Max1024

example10

unit

string

Must be one of:bpskbpsMbpsGbpsTbps

maxDownstreamBurstRate

object

value

integer(int32)

Max1024

example10

unit

string

Must be one of:bpskbpsMbpsGbpsTbps

minDuration

object

The shortest time period that this profile can be deployed.

value

integer(int32)

Min1

example12

unit

string

exampleMinutes

Must be one of:DaysHoursMinutesSecondsMillisecondsMicrosecondsNanoseconds

maxDuration

object

value

integer(int32)

Min1

example12

unit

string

exampleMinutes

Must be one of:DaysHoursMinutesSecondsMillisecondsMicrosecondsNanoseconds

priority

integer(int32)

Min1

Max100

example20

packetDelayBudget

object

value

integer(int32)

Min1

example12

unit

string

exampleMinutes

Must be one of:DaysHoursMinutesSecondsMillisecondsMicrosecondsNanoseconds

jitter

object

value

integer(int32)

Min1

example12

unit

string

exampleMinutes

Must be one of:DaysHoursMinutesSecondsMillisecondsMicrosecondsNanoseconds

packetErrorLossRate

integer(int32)

Min1

Max10

example3

The exponential power of the allowable error loss rate 10^(-N). For instance 3 would be an error loss rate of 10 to the power of -3 (0.001)

Example Response

{
   "name": "QCI_1_voice",
   "description": "QoS profile for video streaming",
   "status": "ACTIVE",
   "targetMinUpstreamRate": {
      "value": 10,
      "unit": "bps"
   },
   "maxUpstreamRate": {
      "value": 10,
      "unit": "bps"
   },
   "maxUpstreamBurstRate": {
      "value": 10,
      "unit": "bps"
   },
   "targetMinDownstreamRate": {
      "value": 10,
      "unit": "bps"
   },
   "maxDownstreamRate": {
      "value": 10,
      "unit": "bps"
   },
   "maxDownstreamBurstRate": {
      "value": 10,
      "unit": "bps"
   },
   "minDuration": {
      "value": 12,
      "unit": "Minutes"
   },
   "maxDuration": {
      "value": 12,
      "unit": "Minutes"
   },
   "priority": 20,
   "packetDelayBudget": {
      "value": 12,
      "unit": "Minutes"
   },
   "jitter": {
      "value": 12,
      "unit": "Minutes"
   },
   "packetErrorLossRate": 3
}

QoD for enhanced communication

Introduction

Relevant terms and definitions

API functionality

Further info and support

QoS Sessions

Available Operations

Creates a new session

Server Variables

Authentication

Request Body Content Typeapplication/json

Example Request

Responses Content Typeapplication/json

Example Response

Session notifications callback callback

Request Body Content Typeapplication/cloudevents+json

Example Payload

Responses

Get QoS session information

Server Variables

Authentication

Path Parameters

Responses Content Typeapplication/json

Example Response

Delete a QoS session

Server Variables

Authentication

Path Parameters

Responses

Extend the duration of an active session

Server Variables

Authentication

Path Parameters

Request Body Content Typeapplication/json

Example Request

Responses Content Typeapplication/json

Example Response

QoS Profiles

Available Operations

Get All QoS Profiles

Server Variables

Query Parameters

Responses Content Typeapplication/json

Example Response

Get QoS Profile for a given name

Server Variables

Path Parameters

Responses Content Typeapplication/json

Example Response

Request Body
Content Type
application/json

Responses
Content Type
application/json

Request Body
Content Type
application/cloudevents+json

Responses
Content Type
application/json

Request Body
Content Type
application/json

Responses
Content Type
application/json

Responses
Content Type
application/json

Responses
Content Type
application/json