Session API

The Centova Cast Session API is very similar to the JSON API, with the notable exception that its method calls do not accept username or password parameters. Instead, it operates in the context of the current Centova Cast user session.

The Session API is primarily useful for adding functionality directly to the Centova Cast interface. This can be accomplished (by experienced developers) by modifying the Centova Cast web interface templates and adding JavaScript code which performs custom AJAX requests to the Session API.

API methods are called via standard HTTP POST requests to the sessionapi.php script in the Centova Cast web root. Note that unlike the JSON API, HTTP GET requests to the Session API are not permitted, as these would make the API vulnerable to CSRF (Cross-Site Request Forgery) attacks.

Just like the JSON API, Centova Cast responds to Session API requests by returning JSON-encoded response data as the payload of the HTTP response.

Session API Request Structure

Requests are passed to the Session API server via POST requests including the following query variables:

• m - Specifies the class name and method to invoke, separated by a period.
  Example: m=system.info

• a - Encapsulates an array of parameters for the API method, in the format a[name]=value.
  Example: a[password]=secret

Example

A typical HTTP request to the Session API might look something like the following:

POST /sessionapi.php HTTP/1.0
Content-Type: application/x-www-form-urlencoded
Content-Length: 33

m=server.switchsource&a[state]=up

The request above would indicate a request to the switchsource method of the server class. One argument, state, is provided with the value of up. When invoked via an AJAX request from an HTML template in the Centova Cast user interface, this particular example would start the autoDJ for the currently logged-in user.

Session API Response Structure

The Session API returns responses identical to those of the JSON API. A JSON response object always contains two top-level properties:

• a type property indicating the type of result: success (corresponding to CSuccess in the API method reference sections) if the request was successful, or error (corresponding to CError in the API method reference sections) if an error occurred, and
• a response property whose value is an object providing the details of the response

Response Content

Within the response object, a message property always contains the a textual description of the result of the request.

The response object may also include a data property containing result data generated by the request. For information about the structure of the data within the data property, consult the Return Value section of the specific API method you wish to call.

Example

A typical JSON response might look something like the following:

{
    "type":"success",
    "response":{
        "data":{
            "size":"1048576",
            "files":"16"
        },
        "message":"Updated"
    }
}

The response packet above would indicate that a request was successfully processed by Centova Cast. A data object with properties size and files was generated by the request.

---