This API should be used to setup a new OTT session for a client device before playback really begins. When used, the SRM verifies that the device and associated account are enabled, and that they have access to the content requested (via a PAV interface); if so creating a session and returning the details for this. After a session has been successfully set up the device may begin playing the content.
To determine if a setup request is completely successful, the client application must examine the payload of the response and ensure it contains a successResponse item (see below). It cannot rely on just the HTTP response code, as SRM returns HTTP 200 codes for denials of session creation for business reasons, like session limit reached or content access denied.
SRM API endpoint URLs are proposed in two forms, with or without a version identifier. If the version identifier is not present, the latest version of the API available on the SRM instance is used. The form with version identifier is suggested to ensure backward compatibility in the case of possible future major evolution of the API.
Request
To use this API, send a HTTP POST request to either of the URLs below:
-
http://<host>:<port>/srm/sessions(uses the latest version) -
http://<host>:<port>/srm/v1/sessions(uses v1)
HTTP Headers
|
Name |
Type |
Description |
Required |
|---|---|---|---|
|
|
String |
Authentication token gained from a positive sign on response.
. |
Yes |
Request body
|
Name |
Type |
Description |
Required |
|---|---|---|---|
|
|
Content JSON object (see below) |
Identifier for the content for which playback is being requested. |
Yes |
Content JSON object
The Content object must contain the following fields.
|
Name |
Type |
Description |
Required |
|---|---|---|---|
|
|
String |
Identifies the content being consumed:
|
Yes |
|
|
String |
Identifies the type of content being requested out of the list of values below:
|
Yes |
Example request body
To request a session to playback a VOD content:
{
"content": {
"contentID": "100001V3D",
"contentType" :"COD"
}
}
To request a session to playback a LIVE channel content:
{
"content": {
"contentID": "BTV_CH1_V",
"contentType": "LIVE"
}
}
Success response
The HTTP response code of 200 is returned with a response body content as shown below:
|
Name |
Type |
Description |
Required |
|---|---|---|---|
|
|
String |
A unique identifier returned for the newly created session; this will be in the form of a UUID (Universally unique identifier). |
Yes |
|
|
Integer |
This is the number of seconds in which the session manager expects a keep-alive request to be received for the session.
|
No |
Example:
{
"successResponse": {
"sessionId": "cfd48f8a-4c33-4c0e-ba52-6632e8810d3e",
"timeout": 30
}
}
Error response
|
Name |
Type |
Description |
Required |
|---|---|---|---|
|
|
String |
The HTTP response code. |
Yes |
|
|
String |
The categorisation of the failure to process the request. |
Yes |
|
|
String |
The specific error code. |
Yes |
|
|
String |
A human readable error message. |
Yes |
For a full list of code, status and errorCode values see the chapter 'SRM API reference / Error Codes and status values' in the Session Resource Manager (SRM) API Documentation.
Example error response for a syntax error in the request:
{
"errorResponse": {
"code": "400",
"status": "ERROR",
"errorCode": "SRM-0002",
"errorMessage": "Malformed request or mandatory parameters missing from request"
}
}
Example error response when the maximum number of sessions for the account has been reached. The client gets an HTTP return code of 200 and the following response payload:
{
"errorResponse": {
"code": "200",
"status": "DENIED",
"errorCode": "SRM-0006",
"errorMessage": "Session Limit Reached"
}
}