.wpb_animate_when_almost_visible { opacity: 1; }

Quality on Demand - CAMARA 0.10 Beta

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

Contact us

Getting started



Introduction

The CAMARA 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.

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 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 operationURL method
I want to get all QoS profiles managed by the Orange Qos serverGET "https://api.orange.com/camara/quality-on-demand/orange-lab/v0/qos-profiles
I want to get all information for one QoS profileGET "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 serverPOST "https://api.orange.com/camara/quality-on-demand/orange-lab/v0/sessions
I want to retrieve QoS session informationGET "https://api.orange.com/camara/quality-on-demand/orange-lab/v0/sessions/{sessionId}
I want to extend current QoS sessionPOST "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 operationURL method
I want to inform a subscribed listener to session event (termination for now)POST "{$request.body#/webhook/notificationUrl

Go up

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 Orange server.

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

NameDescriptionType
nameA unique name for identifying a specific QoS profilestring
descriptionDescription of the QoS profilestring
statusStatus of the QoS Profile - Enum with value: ACTIVE, INACTIVE and DEPRECATED - only ACTIVE are usable to require a QoS sessionstring
targetMinUpstreamRateThe target minimum data rate. Set to zero when no target minimum is defined in this profile. Not managed in Orange Lab implementationRate (see below)
maxUpstreamRateThe maximum best effort data for upstreamRate
maxUpstreamBurstRateThe burst rate for best effort data - Not managed in Orange Lab implementationRate
targetMinDownstreamRateThe target minimum data rate. Set to zero when no target minimum is defined in this profile. Not managed in Orange Lab implementationRate
maxDownstreamRateThe maximum best effort data for downstreamRate
maxDownstreamBurstRateThe maximum best effort burst rate - Equal to targetMinimumUpstreamRate when max is the as the target. Not managed in Orange Lab implementationRate
minDurationThe shortest time period that is supported this profile can be deployedDuration
maxDurationThe maximum length of time that this profile can be deployedDuration (see below)
priorityThe 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 implementationnumber
packetDelayBudgetNot managed in Orange Lab implementationDuration
jitterNot managed in Orange Lab implementationDuration
packetErrorLossRateNot managed in Orange Lab implementationinteger

Rate type is defined as following:

NameDescriptionType
valueThe throughput value in unitnumber
unitenum: Kbps, Mbps, Gbps, Tbpsstring

Duration type is defined as following:

NameDescriptionType
valueThe duration value in unitnumber
unitenum: Nanoseconds, Microseconds, Milliseconds, Seconds, Minutes, Hours, Daysstring

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
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
deviceEnd-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 deviceYes
applicationServerAn object with 2 fields to pass applicationServer with an ipv4Addr or an ipv6Addr. One of them must be provided.See below information on applicationServerYes
devicePortsIf 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.integerNo
applicationServerPortsIf 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.integerNo
qosProfileRequested QoS profile - name of a QoS profilestringYes
webhookAn object with 2 fields to manage notification request.See below information on webhookNo

Following table provides details about device:

Note: One identifier of the four must be provided.

NameDescriptionTypeMandatory
networkAccessIdentifierA public identifier addressing a subscription in a mobile network. In 3GPP terminology, it corresponds to the GPSI.stringNo
phoneNumberA 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 '+'stringNo
Ipv4AddressThe 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 addressNo
Ipv6AddressIPv6 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 )stringNo

Following table provides details about device Ipv4 address:

NameDescriptionTypeMandatory
publicAddressA 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.StringYes
privateAddressA single IPv4 address with no subnet maskStringNo
publicPortTCP or UDP port numberIntegerNo

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.

NameDescriptionTypeMandatory
Ipv4AddressIPv4 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.stringNo
Ipv6AddressIPv6 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 )stringNo

Following table provides details about webhook:

NameTypeFormat
notificationUrlurl where event notification will be postedstring
notificationAuthTokenAuthentification token for callback APIstring

Go up

Summary of response body parameters

All in the request plus following attributes:

NameDescriptionTypeMandatory
sessionIdSession 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
qosStatusCurrent status of the requested Qos sessions. See below value definitionstringYes
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.

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

Go up

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

Go up

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

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

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

Go up

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

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.

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

Summary of session notification body parameters
NameDescriptionTypeMandatory
eventIdUnique identifier of the eventstring (uuid)No - not implemented in our code
eventTypeType of the event . As of now only QosStatusChangedEvent is implementedstringYes
eventTimeDate time when the event occurredstring(datetime)No - not implemented in our code
eventDetailDetail information of the event - see below table definitionobjectYes

The following table provides details about eventDetail structure:

NameDescriptionTypeMandatory
sessionIdSession ID in UUID formatstring (uuid)Yes
qosStatusStatus of the sessionstringYes
statusInfoAdditional information about the statusstringNo - 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 documentmodification datedescription of modifications
1.017/1/2023initialization by Orange CAMARA APIs team
1.125/4/2023corrections by Orange CAMARA APIs team prior to API Offer opening
2.023/08/2023Aligned documentation with version 0.0.9
2.113/09/2023Aligned documentation with implemented notification pattern
2.217/04/2024Implemented the /extend operation

Go up