.wpb_animate_when_almost_visible { opacity: 1; }
CAMARA - Quality on Demand Beta
The Quality-On-Demand (QoD) API provides programmable interface for developers to request improved latency or throughput performance.
0.8

Getting started



Introduction

The CAMARA Quality on Demand API provides a standardized mechanism for requesting, retrieving 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 uri.

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

Subscribe to the API

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

API Authentication

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

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

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

In response, you will get an access_token.

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

Go up

API Description

Summary of resources

This API has one resource managed by QoD server: session.

Optionally, another resource has to be implemented by the API consumer: notifications.

API operation sequence diagram

Following diagram provides an example of QoD api call sequencing :

Summary of methods and URL

As QoD session requester

Use case of operationURL method
I want to get an improved QoS session between an user equipment and an application serverPOST https:// developer.orange.com/apis/qod/v0/sessions
I want to retrieve QoS session informationGET https:// developer.orange.com/apis/qod/v0/sessions/{sessionId}
I want to terminate a QoS session information (before planned end)DELETE https:// developer.orange.com/apis/qod/v0/sessions/{sessionId}

As QoD Server

Use case of operationURL method
I want to inform a subscribed listener to session event (termination for now)POST https:// developer.orange.com/apis/qod/v0/notifications

Go up

Request a session

Summary of request body parameters
NameDescriptionTypeMandatory
durationSession 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 subscribedintegerNo
ueIdAn object with four fields, each of them make possible to pass ueId in different format: externalId , msisdn, ipv4Addr and ipv6AddrSee below information on ueIdYes
asIdAn object with 2 fields to pass asId with an ipv4Addr or an ipv6Addr. One of them must be provided.stringYes
uePortsIf a public ipv4Addr is provided for the ueId object, the port(s) allocated to the UE must also be specified. It could an array of range(s) and/or an array of list.integerNo
asPortsIf a public ipv4Addr is provided for the asId 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.integerNo
qosRequested QoS profile - see QoS profile tablestringYes
notificationUriuri where event notification will be postedstringNo
notificationAuthTokenAuthentification token for callback APIstringNo

Following table provide details about ueId:

NameTypeFormat
externalIdstringExternal Identifier format of the GPSI
msisdnstringSubscriber number in E.164 format (starting with country code). Optionally prefixed with '+'
Ipv4AddrstringIPv4 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.
Ipv6AddrstringIPv6 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 )

Following table provide details about QoS profile:

iddescription
QOS_EQualifier for enhanced communication profile
QOS_SQualifier for the requested QoS profile S
QOS_MQualifier for the requested QoS profile M
QOS_LQualifier for the requested QoS profile L

Go up

Summary of response body parameters

All in the request plus following attributes:

NameDescriptionTypeMandatory
idSession ID in UUID formatstring(uuid)Yes
startedAtTimestamp of session start in seconds since unix epochintegerYes
expiresAtTimestamp of session expiration if the session was not deleted, in seconds since unix epochintegerYes
messagesArray of messages related to the sessionobjectNo

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.

Go up

Example (from msisdn)

Request:

curl -X POST "https://developer.orange.com/apis/qod/v0/sessions"
-H "Authorization: Bearer {your access token}"
-H "Cache-Control: no-cache"  
-H 'accept: application/json'
-H 'Content-Type: application/json'
-d  '{
{
  "duration": 3600,
  "ueId": {
    "msisdn": "+33689748514"
  },
  "asId": {
    "ipv4addr": "192.168.0.1/24"
  },
  "asPorts": {
    "ports": [
      5060,
      5070
    ]
  },
  "qos": "QOS_E",
  "notificationUri": "https://application-server.com/notifications",
  "notificationAuthToken": "c8974e592c2fa...383d4a3960714"
}
}

Response:

201 Session created
Content-Type: application/json
{
  "duration": 3600,
  "ueId": {
    "msisdn": "+33689748514"
  },
  "asId": {
    "ipv4addr": "192.168.0.1/24"
  },
  "asPorts": {
    "ports": [
      5060,
      5070
    ]
  },
  "qos": "QOS_E",
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "startedAt": 1639474600,
  "expiresAt": 1639478200,
  "notificationUri": "https://application-server.com/notifications",
  "notificationAuthToken": "c8974e592c2fa...383d4a3960714"
}

Go up

Most frequent errors

If invalid input are provided in particularfor the ueId a 400 error is triggered. Several errors are documented:

  • msisdn is required as part of ueId
  • ipv4addr is required as part of ueId
  • Some IP address is required as part of ueId
  • UePortsRequired
  • QoSRequired:
  • UePortsRangesNotAllowed
HTTP/1.1 400 Invalid input
Content-Type: application/json
{
  "code": "INVALID_ARGUMENT",
  "status": 400,
  "message": "Expected property is missing: ueId.msisdn"
}

If a session is already existing for the same UE 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 UE"
}

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: ..."
}

Go up

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://developer.orange.com/apis/qod/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,
  "ueId": {
    "msisdn": "+33689748514"
  },
  "asId": {
    "ipv4addr": "192.168.0.1/24"
  },
  "asPorts": {
    "ports": [
      5060,
      5070
    ]
  },
  "qos": "QOS_E",
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "startedAt": 1639474600,
  "expiresAt": 1639478200,
  "notificationUri": "https://application-server.com/notifications",
  "notificationAuthToken": "c8974e592c2fa...383d4a3960714"
}

Go up

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"
}

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://developer.orange.com/apis/qod/v0/sessions/3fa85f64-5717-4562-b3fc-2c963f66afa6"
-H "Authorization: Bearer {your access token}" 
-H 'accept: application/json'

Response:

204 Session deleted

Go up

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. Currently only SESSION_TERMINATED event is implemented. Any other network events are ignored.

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

Summary of request body parameters
NameDescriptionTypeMandatory
sessionIdSession ID in UUID formatstring (uuid)Yes
eventname of the event (defined in an enumeration). As of now only SESSION_TERMINATED is implementedstringYes
Summary of response

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

Example

Request:

curl -X POST "https://{notificationUri}/notifications"
-H "Authorization: Bearer {notificationAuthToken}"
-H "Cache-Control: no-cache"  
-H 'accept: application/json'
-H 'Content-Type: application/json'
-d  '{
  "sessionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "event": "SESSION_TERMINATED"
  },

Response:

```json
204 Successful notification

History of document

Version of the documentmodification datedescription of modifications
1.017/1/2023initialization by Orange CAMARA APIs team

Go up