Getting started - SliceFinity

Quality on Demand

Enable mobile devices to request improved connection quality, ensuring better performance for critical applications.

Introduction

curl -X POST \
-H "Authorization: {{ authorization_header }}" \
-d "grant_type=client_credentials" \
https://api.orange.com/oauth/v3/token

The Quality on Demand API provides a standardized mechanism for requesting, retrieving, extending and terminating a mobile connectivity session with improved performance (bandwidth and latency).

When an application on a mobile device triggers an enhanced QoD, it has to provide expected quality of service (qos) profile between the user equipment (ue) and the application server (as). It may also provide a requested duration, ports, and a notification url.

The QoD server will (if provided) sent a notification to this notification url when the session terminated. In future release we can add other notification type.

You get the Authorization header credentials when you register your application on the Developer Console.

API Authentication

HTTPS requests to the REST API are protected with 2-Legged OAuth. To learn more about how Developer handles authentication, please refer to our documentation.

In short, you will use your Developer Authorization header as authorization_header for the Basic authentication with Developer.

In response, you will get an access_token.

{
       "token_type": "Bearer",
       "access_token": "66AeYJF8eJQ...2SjkFg9LB1LePC",
       "expires_in": "3600"
}

API Description

Summary of resources

This API has two resources managed by QoD server: sessions and qos-profiles .

qos-profiles are the profiles managed by Orange server. A profile is list of technical attributes defining quality on demand performance. This could be considered as ‘catalog’ information.
sessions is a quality on demand session requested to Orange server between a device (defined by IP address & port) to an application on a server (defined by IP address & port). A session request MUST provides both device/application information but also the qos-profiles wished.

API consumer mays provide in POST /sessions a callback URL on which notifications (eg. session termination) regarding the session can be received from the service provider. The notification will be sent to this URL and accordingly to the OAS callback definition

Summary of methods and URL

As QoD session requester:

Use case of operation	URL method
I want to get all QoS profiles managed by the Orange Qos server	GET “https://api.orange.com/camara/quality-on-demand/orange-lab/v0/qos-profiles
I want to get all information for one QoS profile	GET “https://api.orange.com/camara/quality-on-demand/orange-lab/v0/qos-profiles/{name}
I want to get an improved QoS session between an user equipment and an application server	POST “https://api.orange.com/camara/quality-on-demand/orange-lab/v0/sessions
I want to retrieve QoS session information	GET “https://api.orange.com/camara/quality-on-demand/orange-lab/v0/sessions/{sessionId}
I want to extend current QoS session	POST “https://api.orange.com/camara/quality-on-demand/orange-lab/v0/sessions/{sessionId}/extend
I want to terminate a QoS session information (before planned end)	DELETE “https://api.orange.com/camara/quality-on-demand/orange-lab/v0/sessions/{sessionId}

As QoD Server:

Use case of operation	URL method
I want to inform a subscribed listener to session event (termination for now)	POST “{$request.body#/webhook/notificationUrl

Retrieve QoS Profile information

The operation GET “https://api.orange.com/camara/quality-on-demand/orange-lab/v0/qos-profiles allows to get all Qos Profile managed by server.

An array of QoS profile is provided in the response. for each QoS profile following information are provided:

Name	Description	Type
name	A unique name for identifying a specific QoS profile	string
description	Description of the QoS profile	string
status	Status of the QoS Profile – Enum with value: ACTIVE, INACTIVE and DEPRECATED – only ACTIVE are usable to require a QoS session	string
targetMinUpstreamRate	The target minimum data rate. Set to zero when no target minimum is defined in this profile. Not managed in Orange Lab implementation	Rate (see below)
maxUpstreamRate	The maximum best effort data for upstream	Rate
maxUpstreamBurstRate	The burst rate for best effort data – Not managed in Orange Lab implementation	Rate
targetMinDownstreamRate	The target minimum data rate. Set to zero when no target minimum is defined in this profile. Not managed in Orange Lab implementation	Rate
maxDownstreamRate	The maximum best effort data for downstream	Rate
maxDownstreamBurstRate	The maximum best effort burst rate – Equal to targetMinimumUpstreamRate when max is the as the target. Not managed in Orange Lab implementation	Rate
minDuration	The shortest time period that is supported this profile can be deployed	Duration
maxDuration	The maximum length of time that this profile can be deployed	Duration (see below)
priority	The priority that will be given to sessions using this QoS profile, where a lower value indicates a higher priority – set to 0.0 in Orange Lab implementation	number
packetDelayBudget	Not managed in Orange Lab implementation	Duration
jitter	Not managed in Orange Lab implementation	Duration
packetErrorLossRate	Not managed in Orange Lab implementation	integer

Rate type is defined as following:

Name	Description	Type
value	The throughput value in unit	number
unit	enum: Kbps, Mbps, Gbps, Tbps	string

Duration type is defined as following:

Name	Description	Type
value	The duration value in unit	number
unit	enum: Nanoseconds, Microseconds, Milliseconds, Seconds, Minutes, Hours, Days	string

It is also possible to query all information for one QoS profile id by using operation GET “https://api.orange.com/camara/quality-on-demand/orange-lab/v0/qos-profiles/{name}

Request a session

Summary of request body parameters

Name	Description	Type	Mandatory
duration	Session duration in seconds. Maximal value of 24 hours is used if not set. After session has expired the client will receive SESSION_TERMINATED event if subscribed	integer	No
device	End-user equipment able to connect to a mobile network. The API consumer can choose to provide the following specified device identifiers: network access identifier , phone number, ipv4 Address and ipv6 Address. For current implementation on Orange lab we support only ipv4Address.	See below information on device	Yes
applicationServer	An object with 2 fields to pass applicationServer with an ipv4Addr or an ipv6Addr. One of them must be provided.	See below information on applicationServer	Yes
devicePorts	If a public ipv4Addr is provided for the device object, the port(s) allocated to thus user equipment must also be specified. It could an array of range(s) and/or an array of list.	integer	No
applicationServerPorts	If a public ipv4Addr is provided for the application Server object, the port allocated to the application on the server must also be specified. It could an array of range(s) and/or an array of list.	integer	No
qosProfile	Requested QoS profile – name of a QoS profile	string	Yes
webhook	An object with 2 fields to manage notification request.	See below information on webhook	No

Following table provides details about device:

Note: One identifier of the four must be provided.

Name	Description	Type	Mandatory
networkAccessIdentifier	A public identifier addressing a subscription in a mobile network. In 3GPP terminology, it corresponds to the GPSI.	string	No
phoneNumber	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 ‘+’. Optionally prefixed with ‘+’	string	No
Ipv4Address	The device should be identified by either the public (observed) IP address and port as seen by the application server, or the private (local) and any public (observed) IP addresses in use by the device (this information can be obtained by various means, for example from some DNS servers).	See below information on device Ipv4 address	No
Ipv6Address	IPv6 address, following IETF 5952 format, may be specified in form <address/mask>. If address, the /128 subnet is optional for single address (2001:db8:85a3:8d3:1319:8a2e:370:7344 or 2001:db8:85a3:8d3:1319:8a2e:370:7344/128). If address/mask, an IP v6 number with a mask (2001:db8:85a3:8d3::0/64 or 2001:db8:85a3:8d3::/64 )	string	No

Following table provides details about device Ipv4 address:

Name	Description	Type	Mandatory
publicAddress	A single IPv4 address with no subnet mask. In all cases, publicAddress must be specified, along with at least one of either privateAddress or publicPort, dependent upon which is known. In general, mobile devices cannot be identified by their public IPv4 address alone.	String	Yes
privateAddress	A single IPv4 address with no subnet mask	String	No
publicPort	TCP or UDP port number	Integer	No

Note: publicAddress must be provided with either privateAddress or publicPort.

Following table provides details about applicationServer:

Note: One identifier of the two must be provided.

Name	Description	Type	Mandatory
Ipv4Address	IPv4 address may be specified in form <address/mask>. If address we expect an IPv4 number in dotted-quad form 1.2.3.4. Only this exact IP number will match the flow control rule. If address/mask – an IP number as above with a mask width of the form 1.2.3.4/24.	string	No
Ipv6Address	IPv6 address, following IETF 5952 format, may be specified in form <address/mask>. If address, the /128 subnet is optional for single address (2001:db8:85a3:8d3:1319:8a2e:370:7344 or 2001:db8:85a3:8d3:1319:8a2e:370:7344/128). If address/mask, an IP v6 number with a mask (2001:db8:85a3:8d3::0/64 or 2001:db8:85a3:8d3::/64 )	string	No

Following table provides details about webhook:

Name	Type	Format
notificationUrl	url where event notification will be posted	string
notificationAuthToken	Authentification token for callback API	string

Summary of response body parameters

All in the request plus following attributes:

Name	Description	Type	Mandatory
sessionId	Session ID in UUID format	string(uuid)	Yes
startedAt	Timestamp of session start in seconds since unix epoch	integer	Yes
expiresAt	Timestamp of session expiration if the session was not deleted, in seconds since unix epoch	integer	Yes
qosStatus	Current status of the requested Qos sessions. See below value definition	string	Yes
messages	Array of messages related to the session	object	No

Message object features 2 mandatory attributes:

severity: for message severity – mandatory and a string enum with value INFO and WARNING
description: for detailed message text – a mandatory string.

Qos status definition: 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

Example (from msisdn)

Request:

curl -X POST "https://api.orange.com/camara/quality-on-demand/orange-lab/v0/sessions"
-H "Authorization: Bearer {your access token}"
-H "Cache-Control: no-cache"  
-H 'accept: application/json'
-H 'Content-Type: application/json'
-d  '{
{
    "duration": 600,
    "device": {
        "ipv4Address": {
            "publicAddress": "172.20.120.105",
            "privateAddress": "172.20.120.105"
        }
    },
    "applicationServer": {
        "ipv4Address": "172.20.120.84"
    },
    "devicePorts": {
        "ports": [
            50984
        ]
    },
    "applicationServerPorts": {
        "ports": [
            10000
        ]
    },
    "qosProfile": "b55e2cc8-b386-4d90-9f95-b98ba20be050",
    "webhook": {
        "notificationUrl": "https://webhook.site/.....-b450-cfffc51b4c13"
    }
}
}

Response:

201 Session created
Content-Type: application/json

{
    "duration": 600,
    "device": {
        "ipv4Address": {
            "publicAddress": "172.20.120.105",
            "privateAddress": "172.20.120.105"
        }
    },
    "applicationServer": {
        "ipv4Address": "172.20.120.84"
    },
    "devicePorts": {
        "ports": [
            50984
        ]
    },
    "applicationServerPorts": {
        "ports": [
            10000
        ]
    },
    "qosProfile": "b55e2cc8-b386-4d90-9f95-b98ba20be050",
    "sessionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "webhook": {
        "notificationUrl": "https://webhook.site/.....-b450-cfffc51b4c13"
    },
    "startedAt": 1639474600,
    "expiresAt": 1639478200,
    "qosStatus": "REQUESTED"
}

Most frequent errors

If a session is already existing for the same device an error 409 will be sent

HTTP/1.1 409 Conflict
Content-Type: application/json
{
{
  "code": "CONFLICT",
  "status": 409,
  "message": "Another session is created for the same device"
}
}

There are some cases where your client application will no longer gain access to API resources, and get an error back.

Please check the following points:

Here, you attempt to use an expired or revoked access_token and you get an invalid token error. You will have to request a new access_token. As an example:

HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
  "code": "UNAUTHENTICATED",
  "status": 401,
  "message": "Authorization failed: ..."
}

Here, you removed your subscription to the API so that the capability to generate an access_token is not allowed anymore. As an example:

HTTP/1.1 403 Forbidden
Content-Type: application/json
{
  "code": "PERMISSION_DENIED",
  "status": 403,
  "message": "Operation not allowed: ..."
}

Retrieve a session

Summary of request parameters

Only id must be provided as parameter path.

Summary of response body parameters

If session is still existing a complete sessions representation is provided in the response with code 200. See parameters definition for POST request/response.

Example

Request:

curl -X GET "https://api.orange.com/camara/quality-on-demand/orange-lab/v0/sessions/3fa85f64-5717-4562-b3fc-2c963f66afa6"
-H "Authorization: Bearer {your access token}" 
-H 'accept: application/json'

Response:

200 Contains information about active session
Content-Type: application/json

{
  "duration": 3600,
  "device": {
        "ipv4Address": {
            "publicAddress": "172.20.120.105",
            "privateAddress": "172.20.120.105"
        }
    },
  "devicePorts": {
        "ports": [
            50984
        ]
    },
  "applicationServer": {
    "ipv4Address": "192.168.0.1/24"
  },
  "applicationServerPorts": {
    "ports": [
      10000
    ]
  },
  "qosProfile": "b55e2cc8-b386-4d90-9f95-b98ba20be050",
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "startedAt": 1639474600,
  "expiresAt": 1639478200,
  "qosStatus": "REQUESTED",
  "webhook": {
        "notificationUrl": "https://webhook.site/.....-b450-cfffc51b4c13"
    }
}

Most frequent errors

Error is 404 is session did not exist

HTTP/1.1 404 Session not found
Content-Type: application/json
{
  "code": "NOT_FOUND",
  "status": 404,
  "message": "Session Id does not exist"
}

Extend a session

Summary of request parameters

session identifier (sessionId) must be provided as parameter path. In the body, requester must provide a requestedAdditionalDuration which is the additional duration in seconds to be extended.

Summary of response

If the request is accepted, a response 200 and complete session representation are sent back.

Example

Request:

curl -X POST "https://api.orange.com/camara/quality-on-demand/orange-lab/v0/sessions/3fa85f64-5717-4562-b3fc-2c963f66afa6/extend"
-H "Authorization: Bearer {your access token}"
-H "Cache-Control: no-cache"  
-H 'accept: application/json'
-H 'Content-Type: application/json'
-d  '{
{
    "requestedAdditionalDuration": 1200}

Response:

200 Contains information about active session
Content-Type: application/json

{
  "duration": 3600,
  "device": {
        "ipv4Address": {
            "publicAddress": "172.20.120.105",
            "privateAddress": "172.20.120.105"
        }
    },
  "devicePorts": {
        "ports": [
            50984
        ]
    },
  "applicationServer": {
    "ipv4Address": "192.168.0.1/24"
  },
  "applicationServerPorts": {
    "ports": [
      10000
    ]
  },
  "qosProfile": "b55e2cc8-b386-4d90-9f95-b98ba20be050",
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "startedAt": 1639474600,
  "expiresAt": 1639478200,
  "qosStatus": "REQUESTED",
  "webhook": {
        "notificationUrl": "https://webhook.site/.....-b450-cfffc51b4c13"
    }
}

Delete a session

Summary of request parameters

Only id must be provided as parameter path.

Summary of response

If deletion performed a 204 Session deleted is sent as a response (without body)

Example

Request:

curl -X DELETE "https://api.orange.com/camara/quality-on-demand/orange-lab/v0/sessions/3fa85f64-5717-4562-b3fc-2c963f66afa6"
-H "Authorization: Bearer {your access token}" 
-H 'accept: application/json'

Response:

204 Session deleted

Send session notification

Important: this endpoint is to be implemented by the API consumer. The QoD server will call this endpoint whenever any network related event occurs.

QoD server will use notificationUrl and notificationAuthToken as provided in the request.

Summary of session notification body parameters

Name	Description	Type	Mandatory
eventId	Unique identifier of the event	string (uuid)	No – not implemented in our code
eventType	Type of the event . As of now only QosStatusChangedEvent is implemented	string	Yes
eventTime	Date time when the event occurred	string(datetime)	No – not implemented in our code
eventDetail	Detail information of the event – see below table definition	object	Yes

The following table provides details about eventDetail structure:

Name	Description	Type	Mandatory
sessionId	Session ID in UUID format	string (uuid)	Yes
qosStatus	Status of the session	string	Yes
statusInfo	Additional information about the status	string	No – not implemented in our code

Summary of response

If notification is successfully received, a 204 Successful notification is expected as a response (without body)

Example

Request:

curl -X POST "https://{notificationUrl}/notifications"
-H "Authorization: Bearer {notificationAuthToken}"
-H "Cache-Control: no-cache"  
-H 'accept: application/json'
-H 'Content-Type: application/json'
-d  '{
  "eventType": "QosStatusChangedEvent",
  "eventDetail": {
    "sessionId": "8ed2b561-d64c-48ec-bb92-d60421a0147c",
    "qosStatus": "AVAILABLE"
  }
}

Response:

204 Successful notification

History of document

Version of the document	modification date	description of modifications
1.0	17/1/2023	initialization by Orange CAMARA APIs team
1.1	25/4/2023	corrections by Orange CAMARA APIs team prior to API Offer opening
2.0	23/08/2023	Aligned documentation with version 0.0.9
2.1	13/09/2023	Aligned documentation with implemented notification pattern
2.2	17/04/2024	Implemented the /extend operation

We’re winners of Innovate UK’s “New Innovators in Communication Networks 2024” grant award. Read more

Patent Pending | GB 2403018.1 and US 19/067196

Quality on Demand

Introduction

API Authentication

API Description

Summary of resources

Summary of methods and URL

Retrieve QoS Profile information

Request a session

Summary of request body parameters

Summary of response body parameters

Example (from msisdn)

Most frequent errors

Retrieve a session

Summary of request parameters

Summary of response body parameters

Example

Most frequent errors

Extend a session

Summary of request parameters

Summary of response

Example

Delete a session

Summary of request parameters

Summary of response

Example

Send session notification

Summary of session notification body parameters

Summary of response

Example

History of document

Interested? Contact us to get more information.

How can we help?

Social Media

Quick links

Policy

Quality on Demand

Introduction

Subscribe to the API

API Authentication

API Description

Summary of resources

Summary of methods and URL

Retrieve QoS Profile information

Request a session

Summary of request body parameters

Summary of response body parameters

Example (from msisdn)

Most frequent errors

Retrieve a session

Summary of request parameters

Summary of response body parameters

Example

Most frequent errors

Extend a session

Summary of request parameters

Summary of response

Example

Delete a session

Summary of request parameters

Summary of response

Example

Send session notification

Summary of session notification body parameters

Summary of response

Example

History of document

Interested? Contact us to get more information.

How can we help?

Social Media

Quick links

Policy