Feedback
Table Of Contents
Introduction to Cisco TV CDS Software APIs
RTSP Stream Diagnostics Requests
RTSP Stream Diagnostics Response
Message Flow for RTSP Stream Diagnostics APIs
Introduction to Cisco TV CDS Software APIs
Cisco TV Content Delivery System (CDS) software provides two sets of application program interfaces (APIs):
•
Monitoring
•
The Monitoring APIs use an HTTP GET message format for sending control messages between any HTTP client and the Cisco CDS.
The RTSP Stream Diagnostics APIs use eXtensible Markup Language (XML) over Hypertext Transfer Protocol (HTTP) for sending control messages between any HTTP client and the Cisco CDS.
The APIs can be used to monitor the states of specified CDS functions. Table 1-1 describes these APIs.
This chapter contains the following sections:
•
Connection
Any HTTP client that can send a request to the Content Delivery System Manager (CDSM) in the proper format can be used to send the API messages.
Connections can be semi-persistent or persistent; that is, the connection can be used for a single request-response pair or multiple request-response pairs.
A standard set of HTTP headers is used for all HTTP requests and responses. These headers include the content type, the content length, and a sequence number.
The HTTP request transmitter is considered the client and the HTTP request receiver is considered the server. The client always initiates the connection. The client must either receive a response or time out a request before sending another request on the same connection. The same connection can be used for multiple requests. However, when the client sends a new request, if there is already a connection established for a previous request for which the client is expecting a response from the server, then the client must open a new connection for the new request.
The API messages require a bidirectional socket connection for sending an HTTP request and receiving an HTTP response. The persistent protocol maintains a connection between requests until either the client or server indicates that the socket should close. This is typical of HTTP/1.0.
Persistent connections are handled using the traditional mechanisms specified in HTTP. In HTTP/1.0, connections are persistent by default. The HTTP response must include the header "Connection: close" in order to indicate that the connection will be closed at the end of transmission. During periods when no messages are being exchanged, the client or server may close the connection to conserve resources. The recommended connection approach is to use the default HTTP/1.0 behavior and to use the same connection for all requests.
HTTP Headers
This section covers the HTTP header formats for the request messages and the response messages.
Request Messages
There are two different request message formats:
•
•
Monitoring Requests
The Monitoring APIs use an HTTP GET message format. All parameters are included in the HTTP GET message.
Table 1-2 provides an overview of the expected input parameters for each request message.
RTSP Stream Diagnostics Requests
For RTSP Stream Diagnostic requests, regardless of the request type, the same HTTP request header format is used. Basic request requirements include the following:
•
•
•
•
Required entity headers are the following:
•
•
•
Other entity headers are optional. For example, the HTTP header may include a date header. However, non-required entity headers may be ignored by the server.
The URI specifies the root service for the message followed by the query string. The query string has the syntax of action=<xml root tag>. The URI always begins with the service name. For example, if the service name is PlayoutDetails and the XML root tag is <GetCurrentlyPlayingDetails>, the URI is /apis/PlayoutDetails?action=GetCurrentlyPlayingDetails.
The following example is the complete HTTP POST message:
POST /apis/PlayoutDetails?action=GetCurrentlyPlayingDetails HTTP/1.0User-Agent: HTTPTool/1.0Content-Type: text/xmlContent-Length: 60CSeq: 123<?xml version="1.0" encoding="utf-8"?> <GetCurrentlyPlayingDetails />Response Messages
There are two different response message formats:
•
•
Monitoring Response
All response messages for the Monitoring APIs return an XML document.
RTSP Stream Diagnostics Response
The same HTTP response header is used regardless of the response type. The status code and status text in the response indicate whether the server received and processed the request. Some HTTP response messages consist of only the HTTP header, while others consist of both the HTTP header and XML message body.
The only required entity header is cseq, which is a unique numeric ID.
The only required entity header for the XML message body is the content-type, text/xml.
Other entity headers are optional. For example, the HTTP header may include a date header. However, non-required entity headers may be ignored by the client when processing the response.
The sequence number specified in the HTTP-response must match the sequence number in the HTTP request.
The status codes and status text are specific to the HTTP-response. Chapter 2, "Monitoring APIs" and Chapter 3, "RTSP Stream Diagnostics APIs" provide a list of appropriate status codes for each message.
The following example is an HTTP response with no XML body:
HTTP/1.0 200 OKDate: Mon, 02 Jun 2008 22:50:45 GMTCSeq: 123The following example is an HTTP response with the XML body (body not shown):
HTTP/1.0 200 OKDate: Mon, 02 Jun 2008 22:50:45 GMTServer: Apache/1.3.33 (UNIX) PHP/4.4.8X-Powered-By: PHP/4.4.8Connection: closeContent-Type: text/xmlCSeq: 123Message Flow for RTSP Stream Diagnostics APIs
This section covers the HTTP message flow and possible causes for incomplete message transactions.
Request and Response
The client connects to the server, sends an HTTP request, and waits for an HTTP response. During this time, the client must not send any other requests using this connection. The client can establish a separate connection to send another request in parallel.
The server processes the request and sends an HTTP response to the client on the same connection on which it received the request. The response must use the same sequence number that was specified in the request. When the client receives the response, it validates the sequence number before processing the response.
Based on the HTTP headers, the client or server may close the connection or the connection may be left open for subsequent requests from the client. The client can have several open connections to the server at any given time.
Request Timeout
The client sets a timer when it sends an HTTP request. This timer represents the maximum amount of time the client waits for a response from the server. A typical timeout period is five seconds.
If the client fails to receive an HTTP response before the timer expires, the client must consider the request as failed. The client can discard the request, immediately retry the request, or retry the request at a later time. The method of handling the failure is implementation-specific, and may vary by importance of the request type.
Invalid Sequence Number
When the client receives an HTTP response with a sequence number that differs from the request sequence number, the client discards the message and continues to wait for a valid response until the timeout threshold has been reached.
Connection Lost
During the HTTP transaction, if the connection to the server is lost at any time prior to receiving a valid HTTP response message, the client must consider the request has failed. The client should immediately retry the request. If the retry fails, the client can discard the request or retry the request at a later time. The method of handling the failure is implementation-specific, and may vary by the importance of the request type.
In most cases, the server has started processing the request prior to the connection loss. The server should finish processing the request. The server must not establish a connection with the client in order to return the response. It is up to the client to reconnect and retransmit the request.