Quality on Demand - CAMARA - Romania - Sandbox 0.11

Getting started

• Introduction
  • Subscribe to the API
  • API Authentication
  • API Description
    • Summary of resources
    • Summary of methods and URL
    • Request a session
      • Summary of request body parameters
      • Summary of response body parameters
      • Example (from ip)
    • Most frequent errors
    • Retrieve a session by id
      • Summary of request parameters
      • Summary of response body parameters
      • Example
    • Retrieve a list of session
      • Summary of request parameters
      • Summary of response body parameters
      • Example (from msisdn)
    • 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

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

        
        Copied 
      

In response, you will get an access_token.

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

        
        Copied 
      

Go up

API Description

Summary of resources

This API manages sessions resource.

Note: Previously this API managed as well qos-profiles resource but from v0.11 this one is managed in a separate API

• 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:

As QoD Server:

Go up

Request a session

Summary of request body parameters

Following table provides details about device identifier:

Note: One identifier of the four must be provided.

Following table provides details about device Ipv4 address:

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.

Following table provides details about sinkCredential:

Go up

Summary of response body parameters

All in the request plus following attributes:

QosStatus values:

• 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

statusInfo values:

• 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

Go up

Example (from ip)

Request:

curl -X POST "https://api.orange.com/camara/orange-lab/quality-on-demand/v0.11/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",
    "sink": "https://webhook.site/.....-b450-cfffc51b4c13",
    "sinkCredential": {
        "credentialType": "ACCESSTOKEN",
        "accessToken": "qsdfr45jh..444",
        "accessTokenExpiresUtc" : "2024-12-01T12:00:00Z",
        "accessTokenType": "bearer"
    }
}
}

        
        Copied 
      

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",
    "sink": "https://webhook.site/.....-b450-cfffc51b4c13",
    "sinkCredential": {
        "credentialType": "ACCESSTOKEN",
        "accessToken": "qsdfr45jh..444",
        "accessTokenExpiresUtc" : "2024-12-01T12:00:00Z",
        "accessTokenType": "bearer"
    }
    "startedAt": 1639474600,
    "expiresAt": 1639478200,
    "qosStatus": "REQUESTED"
}

        
        Copied 
      

Go up

Most frequent errors

If the session could not provided because of issue with the device identifier a error 422 will be sent.

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

        
        Copied 
      

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

        
        Copied 
      

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

        
        Copied 
      

Go up

Retrieve a session by id

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/orange-lab/quality-on-demand/v0.11/sessions/3fa85f64-5717-4562-b3fc-2c963f66afa6"
-H "Authorization: Bearer {your access token}" 
-H 'accept: application/json'

        
        Copied 
      

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": "AVAILABLE",
  "sink": "https://webhook.site/.....-b450-cfffc51b4c13",
  "sinkCredential": {
        "credentialType": "ACCESSTOKEN",
        "accessToken": "qsdfr45jh..444",
        "accessTokenExpiresUtc" : "2024-12-01T12:00:00Z",
        "accessTokenType": "bearer"
    }
}

        
        Copied 
      

Go up

Retrieve a list of session

Summary of request parameters

A device identifier must be provided. See above table describing device identifiers. Operation POST is used.

Summary of response body parameters

A list of sessions for the device identifier in the request are provided. The respone will provide an array of session resource. Each resource is described as in the "retrieve a session by id" response.

Example (from msisdn)

Request:

curl -X POST "https://api.orange.com/camara/orange-lab/quality-on-demand/v0.11/retrieve-sessions"
-H "Authorization: Bearer {your access token}"
-H "Cache-Control: no-cache"  
-H 'accept: application/json'
-H 'Content-Type: application/json'
-d  '{
{
    "device": {
        "ipv4Address": {
            "publicAddress": "172.20.120.105",
            "privateAddress": "172.20.120.105"
        }
    }
}
}

        
        Copied 
      

Response:

A collection of sessions.

Most frequent errors

Note that an empty list is not considered as an error.

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/orange-lab/quality-on-demand/v0.11/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}

        
        Copied 
      

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": "AVAILABLE",
  "sink": "https://webhook.site/.....-b450-cfffc51b4c13",
  "sinkCredential": {
        "credentialType": "ACCESSTOKEN",
        "accessToken": "qsdfr45jh..444",
        "accessTokenExpiresUtc" : "2024-12-01T12:00:00Z",
        "accessTokenType": "bearer"
    }
}

        
        Copied 
      

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/orange-lab/quality-on-demand/v0.11/sessions/3fa85f64-5717-4562-b3fc-2c963f66afa6"
-H "Authorization: Bearer {your access token}" 
-H 'accept: application/json'

        
        Copied 
      

Response:

204 Session deleted

        
        Copied 
      

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

The following table provides details about eventDetail structure:

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

        
        Copied 
      

Response:

204 Successful notification

        
        Copied 
      

History of document

Go up