Getting Started - QoS Profiles API

• Introduction
• API Scope
• Subscribe to the API
• API Authentication
  • API Description
  • Base URL
  • Resources
    • /retrieve-qos-profiles (POST)
      • Request
      • Response
    • /qos-profiles/{name} (GET)
      • Request
      • Response
  • Most frequent errors
• Looking for support?

Introduction

The Quality-of-Service (QoS) Profiles API provides a set of predefined network performance characteristics, such as latency, throughput, and priority, identified by a unique name. These profiles allow application developers to specify the desired network behavior for their application's data traffic, ensuring optimal performance. By selecting an appropriate QoS profile, developers can request stable latency (reduced jitter) or throughput for specific data flows between client devices and application servers when used by the Quality-On-Demand APIs.

API Scope

The current API implementation is applicable to any mass-market Orange Spain customer.

When to use this API?

It is mandatory in a Quality on Demand request to provide a QoS profile. This QoS Profile API allows to retrieve the profiles proposed by Orange Spain for a given line.

Subscribe to the API

You have to register your application on the Orange Developer Console and subscribe to it.

API Authentication

HTTPS requests to the REST API are protected with CIBA 3-Legged OAuth.

In short, the API Invoker (e.g. Application Backend or Aggregator) before requesting QoS Profiles information, needs to request an Access Token from Orange Authorization Server. The process follows the OpenID Connect Client-Initiated Backchannel Authentication (CIBA) flow for 3-legged authentication.

Step 1: Request the OAuth authorization code from the Application Backend

The API Invoker provides in the authorization request (/bc_authorize) a login_hint with a valid User identifier together with the application credentials (client_assertion & client_assertion_type) and indicates the Purpose for processing Personal Data. The Orange implementation follows the CAMARA scope definition. The scope must be set to: openid dpv:<dpvValue> qos-profiles:read. dpv stands for Data Privacy Vocabulary.

Note on JWT usage via client assertion: client_assertion is a JWT used by a client to authenticate itself to an authorization server, while client_assertion_type specifies the type of assertion being used, typically indicating it is a JWT. Together, they facilitate secure client authentication in OAuth 2.0 and OpenID Connect protocols. API consumer has to define JWK keystore in settings tab of the application in Orange Developer.

Current supported DPV values include, but are not limited to:

• FulfilmentOfContractualObligation

Example: to retrieve QoS Profiles, in a context of service provision, the scope in the bc-authorize must be set to openid dpv:FulfilmentOfContractualObligation qos-profiles:read

Orange Authorization Server will check if the owner of the phone number did not opt-out to authorize access to this data. If this is not the case, a response 200 is sent back with an authorization request identifier (auth_req_id). If the resource owner or OpenID Provider denied the request, an error 403 Forbidden is sent back.

Request:

curl -X POST \
  'https://api.orange.com/es/openapi/oauth/v2/bc-authorize' \
  --header 'Accept: */*' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'login_hint=tel:+33654654654' \
  --data-urlencode 'client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer' \
  --data-urlencode 'client_assertion=ey...xzw' \
  --data-urlencode 'scope=openid dpv:FulfilmentOfContractualObligation qos-profiles:read'

Response:

200
Content-Type: application/json

{
  "auth_req_id": "69957d77-...-b29f22e61307",
  "expires_in": 120,
  "interval": 2
}

Step 2: Request the OAuth access token

Once the client application gets the authorization code, the API Invoker polls the token endpoint by making an "HTTP POST" request by sending the grant_type (urn:openid:params:grant-type:ciba), auth_req_id (OperatorAuthReqId) and the application credentials (client_assertion & client_assertion_type) parameters.

If the transaction succeeds, in the POST response, the access_token is provided.

Request:

curl -X POST \
  'https://api.orange.com/es/openapi/oauth/v2/token' \
  --header 'Accept: */*' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer' \
  --data-urlencode 'client_assertion=eyJhbGciOi...zif0Tjxzw' \
  --data-urlencode 'auth_req_id=69...07' \
  --data-urlencode 'grant_type=urn:openid:params:grant-type:ciba'

Response:

200
Content-Type: application/json

{
  "access_token": "OFR_28FpNfX...7lwFAg3LR0vmHCOmJAg7Si",
  "token_type": "Bearer",
  "expires_in": 119
}

Step 3: Access protected resources using OAuth access token

In order to call our API, the access_token is mandatory.

Specific documentation about QoS Profiles resources is provided below.

API Description

Base URL

The Base URL is the first part of the full invocation URL, just before the resource paths defined in the API reference.

The Base URL is comprised of the scheme ('https'), the authority (i.e. the Fully Qualified Domain Name) and the API base path.

Whenever you request this API and encounter a 404 (Not Found) HTTP status code, please check first that the Base URL is correct.

The Base URL for this API is: https://api.orange.com/camara/oes/qos-profiles/v1

The documentation below assumes that, whenever you make requests on this API, you are prepending the Base URL to the resource paths defined for this API.

Resources

This API has two resources.

/retrieve-qos-profiles (POST)

Retrieve all QoS Profiles that match the given criteria.

Notes:

• The access token must be a 3-legged access token.
• All returned QoS Profiles will be available to the subject (device) associated with the access token.

For current implementation only 3-legged accesstoken are managed.

Request

As an example:

curl  -X POST \
  'https://api.orange.com/camara/oes/qos-profiles/v1/retrieve-qos-profiles' \
  --header 'Accept: */*' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer xxxx' \
  --data-raw '{
  "status": "ACTIVE"
}'

Response

a/ If the transaction succeeds

On success, the QoS Profiles API returns a 200 OK HTTP status code with JSON data including an array of QoS profiles.

As an example:

HTTP/1.1 200 OK

[
  {
    "name": "TI_L_B2B",
    "description": "Traffic Differentiation based on QCI/5QI (relative priority: 5:1)",
    "status": "ACTIVE",
    "maxUpstreamRate": {},
    "maxUpstreamBurstRate": {},
    "targetMinDownstreamRate": {},
    "maxDownstreamRate": {},
    "maxDownstreamBurstRate": {},
    "minDuration": {
      "value": 60,
      "unit": "SECONDS"
    },
    "maxDuration": {
      "value": 84600,
      "unit": "SECONDS"
    },
    "priority": 5,
    "packetDelayBudget": {},
    "jitter": {}
  },
  {
    "name": "TI_S_B2B",
    "description": "Traffic Differentiation based on QCI/5QI (relative priority: 2:1)",
    "status": "ACTIVE",
    "maxUpstreamRate": {},
    "maxUpstreamBurstRate": {},
    "targetMinDownstreamRate": {},
    "maxDownstreamRate": {},
    "maxDownstreamBurstRate": {},
    "minDuration": {
      "value": 60,
      "unit": "SECONDS"
    },
    "maxDuration": {
      "value": 84600,
      "unit": "SECONDS"
    },
    "priority": 2,
    "packetDelayBudget": {},
    "jitter": {}
  }
]

b/ If the transaction fails

Please visit the most frequent errors section in this page.

/qos-profiles/{name} (GET)

Get a specific QoS Profile by name.

The access token must be a 3-legged access token. QoS Profile are only returned if available for the phoneNumber associated with the access token.

Request

As an example:

curl  -X GET \
  'https://api.orange.com/camara/oes/qos-profiles/v1/qos-profiles/TI_L_B2B' \
  --header 'Accept: */*' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer xxxx'

Response

a/ If the transaction succeeds

On success, the QoS Profiles API returns a 200 OK HTTP status code with JSON data including the QoS profile details.

The response structure is the same as for the /retrieve-qos-profiles endpoint, but returns a single QoS profile object instead of an array.

As an example:

HTTP/1.1 200 OK

{
  "name": "TI_L_B2B",
  "status": "ACTIVE",
  "maxUpstreamRate": {},
  "maxUpstreamBurstRate": {},
  "targetMinDownstreamRate": {},
  "maxDownstreamRate": {},
  "maxDownstreamBurstRate": {},
  "minDuration": {
    "value": 60,
    "unit": "SECONDS"
  },
  "maxDuration": {
    "value": 84600,
    "unit": "SECONDS"
  },
  "priority": 5,
  "packetDelayBudget": {},
  "jitter": {}
}

b/ If the transaction fails

Please visit the most frequent errors section in this page.

Most frequent errors

If invalid input is provided, in particular for the device identifier, a 400 error is triggered.

HTTP/1.1 400 Bad Request
Content-Type: application/json
{
  "status": 400,
  "code": "INVALID_ARGUMENT",
  "message": "Client specified an invalid argument, request body or query param."
}

If the client provided a phone number within the access token but also provides it in the API payload, an error 422 is sent back.

HTTP/1.1 422 Unprocessable Content
Content-Type: application/json
{
  "status": 422,
  "code": "UNNECESSARY_IDENTIFIER",
  "message": "The device is already identified by the access token."
}

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
{
  "status": 401,
  "code": "UNAUTHENTICATED",
  "message": "Request not authenticated due to missing, invalid, or expired credentials. A new authentication is required."
}

• 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
{
  "status": 403,
  "code": "PERMISSION_DENIED",
  "message": "Client does not have sufficient permissions to perform this action."
}

• Resource not found (it can be an error in the path suffix of the URL, or an unknown QoS profile name):

HTTP/1.1 404 Not Found
Content-Type: application/json
{
  "status": 404,
  "code": "NOT_FOUND",
  "message": "The specified resource is not found."
}

• Device identifier not found:

HTTP/1.1 404 Not Found
Content-Type: application/json
{
  "status": 404,
  "code": "IDENTIFIER_NOT_FOUND",
  "message": "Device identifier not found."
}

• Exceeded requests per hour/minute limit:

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
{
  "status": 429,
  "code": "TOO_MANY_REQUESTS",
  "message": "Rate limit reached."
}

Looking for support?

Facing technical issue when using this API?

Please contact us