Sending keep-alive calls

Session keep-alive

This API should be used to maintain an active OTT session for a client device. Concurrent to the content playout, the client application periodically issues keep-alive requests. When received, the SRM checks the session state and if still valid, identifies 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 keep-alive 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} (uses the latest version)
http://<host>:<port>/srm/v1/sessions/{sessionId} (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

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

Request parameters

Name	Type	Description	Required
`sessionId`	String	A unique identifier for the session; this will be in the form of a UUID (Universally unique identifier). It must be the value received in the `successResponse` from the session setup request.	Yes

Success response

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

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

CODE

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

CODE

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