Setting up OTT sessions

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
`Client-Token`	String	Authentication token gained from a positive sign on response. For details of obtaining a token, see Authentication.	Yes

Request body

Name	Type	Description	Required
`content`	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
`contentID`	String	Identifies the content being consumed: For VOD this should be a valid CMS Origin Key value identifying a COD Asset For TimeShift/StartOver, Live Broadcast this should be a valid CMS Origin Key for a BTV Channel For Catchup and NPVR this should be a valid Broadcast Event CMS Origin Key	Yes
`contentType`	String	Identifies the type of content being requested out of the list of values below: `COD` - for VOD content `CU` - for Catch-up content `TS` - for Timeshift / StartOver content `NPVR` - for NPVR content `LIVE` - for live broadcast content	Yes

Example request body

To request a session to playback a VOD content:

CODE

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

To request a session to playback a LIVE channel content:

CODE

{
    "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
`sessionId`	String	A unique identifier returned for the newly created session; this will be in the form of a UUID (Universally unique identifier).	Yes
`timeout`	Integer	This is the number of seconds in which the session manager expects a keep-alive request to be received for the session. If this request is not received in the specified grace period, the session will be cleaned up by the session manager. If the timeout is not specified then the keep-alive feature has been disabled for this session.	No

Example:

CODE

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

Error response

Name	Type	Description	Required
`code`	String	The HTTP response code.	Yes
`status`	String	The categorisation of the failure to process the request.	Yes
`errorCode`	String	The specific error code.	Yes
`errorMessage`	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:

CODE

{
    "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:

CODE

{
    "errorResponse": {
        "code": "200",
        "status": "DENIED",
        "errorCode": "SRM-0006",
        "errorMessage": "Session Limit Reached"
    }
}

Request

HTTP Headers

Request body

Content JSON object

Example request body

Success response

Error response

See also