JSON API

The Centova Cast JSON API provides a simple JSON-based interface to Centova Cast's automation API. API methods are called via standard HTTP GET or POST requests to the api.php script in the Centova Cast web root, in which the request parameters are passed as simple GET or POST variables.

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

JSON API Request Structure

Requests are passed to the JSON API server via GET or POST requests including the following query variables:

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

• f - Always set to json, to request a JSON-formatted response.
  Example: f=json

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

Example

A typical JSON request might look something like the following: <!-- break-at: a[password] -->

http://example.com:2199/api.php?xm=server.getstatus&f=json&a[username]=jdoe&a[password]=secret

The URL above would indicate a request to the getstatus method of the server class. Two arguments, username and password, are provided with values jdoe and secret, respectively.

While the JSON API supports both GET and POST requests, it is typically more secure to use POST requests since GET request parameters (which may contain passwords) are logged to the web server's access log.

JSON API Response Structure

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":[
        {
        "username":"jdoe",
        "state":"up",
        "expected":"up",
        "sourcestate":"up",
        "sourceexpected":"up"
        }
    ],
    "message":"Check complete"
    }
}

The response packet above would indicate that a request was successfully processed by Centova Cast. One result row was generated by the request, which contained fields entitled username, state, expected, sourcestate, and sourceexpected, whose values were jdoe, up, up, up, and up, respectively.

Had the response included additional result rows, these would have been represented by additional elements within the data array.

---