OTT session management

Important note:  From ML2.8 onwards OTT session management is provided by the OTT SRM module. Information concerning session management provided by SDP for earlier releases can be found at the bottom of this page.

Summary

OpenTV Platform provides OTT session management to limit the number of concurrent streams and control the amount of bandwidth consumed by client apps. Account profiles can include a maximum number of concurrent OTT streams. The client apps will attempt to set-up a session for each new play-back session and SRM will enforce this limitation, delegating the final check to SDP. In addition, SRM offers an API for the operator to retrieve the existing sessions of a given customer account and tear-down an existing session at any point in time.

The following diagram illustrates the simplified logical flow of the client application for the nominal use case

SRM API methods

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 will be used. The form with version identifier is suggested to ensure backward compatibility in the case of possible future major evolution of the API.

Session Setup

This API should be used to set up a new OTT session for a client device, before playback really begins.

When used, the SRM will verify 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.

In order 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.

To use this API, send a HTTP POST request to either of the URLs below:

http://<host>:<port>/srm/sessions

http://<host>:<port>/srm/v1/sessions

HTTP Headers

Request Body

Content JSON Object

The Content object must contain the following fields.

Example Request Body

Request a session to playback a VOD content:

{
    "content": {
        "contentID": "100001V3D",
        "contentType" :"COD"
    }
}

Request a session to playback a LIVE channel content

{
    "content": {
        "contentID": "BTV_CH1_V",
        "contentType": "LIVE"
    }
}

Success Response

HTTP response code of "200" is returned with a response body content as below:

Example:

{
    "successResponse": {
        "sessionId": "cfd48f8a-4c33-4c0e-ba52-6632e8810d3e",
        "timeout": 30
    }
}

Error Response

For a full list of code, status and errorCode values see the chapter "SRM API reference / Error Codes and status values" in SRM User Guide

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

Session Keep-alive

This API should be used to maintain an active OTT session for a client device. Concurrently to the content playout, the client application will periodically issue keep-alive requests.  When recieved, the SRM will check the session state, if still valid it will identify the session as being active returning a positive response to the client.

Where a client does not request a keep-alive for a session within a configured time period, that session will become a candidate for removal, with further client access to that session resulting in an error response. The time period within which a keepalive is expected by the session manager for the session, is included in the "timeout" field of a successful SETUP response message. If no "timeout" value has been specified the client should assume that keepalive requests are not required for this session and should not be sent.

It is recommended that the keep-alive period is less than half of that of the timeout period set on SRM, to allow for significant fault tolerance.
To use this API, send an HTTP PUT request to either of the URLs below:

http://<host>:<port>/srm/sessions/{sessionId}

http://<host>:<port>/srm/v1/sessions/{sessionId}

HTTP Headers

It is assumed that the client will maintain a valid authentication token to be included in this request.

Request Parameters

Success Response

HTTP response code of "200" will be returned with no response payload.

Error Response

For a full list of code, status and errorCode values see the chapter "SRM API reference / Error Codes and status values" in SRM User Guide

Example error responses:

{
    "errorResponse": {
        "code": "400",
        "status": "ERROR",
        "errorCode": "SRM-0002",
        "errorMessage": "Malformed request or mandatory parameters missing from request"
    }
}

{
    "errorResponse": {
		"code": "404",
        "status": "ERROR",
        "errorCode": "SRM-0008",
        "errorMessage": "Session Not Found"
    }
}

Error Handling

The client application is expected to behave as follows in certain error situations:

• Failure to receive response/timeout
  • Client sends keepalive request for session to the session manager.
  • Client does not receive a response from session manager.
    • If the session timeout period has not yet been reached the client is free to re-attempt the session keep-alive using a new request within half the configured timeout period.
    • If the session timeout period has been exceeded the client should send a tear-down request for the session and attempt to setup a new session if required (i.e. OTT stream is still active).

• Error response
  • Client sends a keepalive request for the session to the session manager
  • Client receives an error response from the session manager
    • Client should send a tear-down request for the session and then attempt to setup a new session if required (i.e. OTT stream is still active). If an attempt is made to setup a new session without issuing a tear-down of the old session when the account maximum number sessions is reached, SRM will refuse to create the new session. The client will have to wait untill one of the old sessions times-out and SRM "expires" it.

Session Tear-down

This API should be used to close an active OTT session for a client device.

When received, the SRM will mark the session as ended and ready for removal. Thus the number of active sessions for the account is decremented, allowing the possibility for a new session to be subseqeuntly created.

To use this API, send an HTTP DELETE request to one of the following URL's:

http://<host>:<port>/srm/sessions/{sessionId}

http://<host>:<port>/srm/v1/sessions/{sessionId}

HTTP Headers

It is assumed that the client will maintain a valid authentication token to be included in this request.

Request Parameters

Success Response

HTTP response code of "200" will be returned with no response payload.

Error Response

For a full list of code, status and errorCode values see the chapter "SRM API reference / Error Codes and status values" in SRM User Guide

Example error responses:

{
    "errorResponse": {
        "code": "400",
        "status": "ERROR",
        "errorCode": "SRM-0002",
        "errorMessage": "Malformed request or mandatory parameters missing from request"
    }
}

Error Handling

The client application is expected to behave as follows in certain error situations occurring for a tear-down request:

• Failure to receive response/timeout
  • Client sends tear-down request for session to the session manager.
  • Client does not receive a response from session manager.
    • If the session timeout period has not yet been reached the client is free to re-attempt the tear-down using a new request within half the configured timeout period.
    • If the session timeout period has been exceeded the client should assume the session to be closed.
    • If the session timeout period is not set then the client is free to re-attempt the tear-down using a new request N times within T period; after this period the session can be assumed to be closed.

• Error response
  • Client sends teardown request for session to the session manager.
  • Client receives an error response from the session manager.
    • The client should assume the session to be closed.

Pre ML2.8, Interface to SDP

As well as the information provided here, see also the full SDP API documentation.

Data Models

{ 
    "UID" : 153,
    "accountUID" : 27,
    "contentUID" : 126,
    "contentType" : "PRG",
    "deviceId" : 36,
    "allocatedDate" : "12-12-2013",
    "status" : "LIVE",
    "expiryDate" : "12-12-2015"
}

Use Cases

Set up an OTT Session

Setup API is used to create a new OTTSession on SDP.

GET http://server:port/adaptor/hue-gateway/gateway/http/js/ottSession/setUp

After successful creation, the OTT Session object is returned in the response.

Tear-down an OTT Session

TearDown API is used to delete an OTTSession on SDP.

GET http://server:port/adaptor/hue-gateway/gateway/http/js/ottSession/tearDown

After successful deletion, the sessionId of the deleted OTT Session is returned in the response.

Retrieve list of active OTT Session Media Players

Retrieve API is used to retrieve the list of active OTT sessions Media Player.

GET http://server:port/adaptor/hue-gateway/gateway/http/js/ottSession/getMPDevicesWithOpenSessions

This call returns a list of Media Player items that are associated with an active OTTSession.