Entertonement API - Requests and Response
API Requests and Responses
Overview
The Entertonement API is built on the REST architecture, allowing applications to be written simply by implementing the necessary HTTP requests and responses.
Requests
Interaction with Entertonement is done via HTTP GET, POST, PUT and DELETE requests. When uploading content, attach files use the "multipart/form-data" content type that is used for traditional file uploads.
POST requests are representative of storing data on Entertonement and therefore require authentication. See the Authentication page for details.
Formats
Requests can choose a response format by appending .[format] to the end of the request url. The two available are json and xml. For example, to request a clip by id in JSON format, request http://www.entertonement.com/clips/1400.json.
Responses
Successful responses will include an HTTP 200 OK status code in the headers. If there are errors, in addition to error messages in the response, a representative HTTP status code will be sent:
403 Forbidden - The client's authentication failed 404 Not Found - The client requested a resource that could not be found 500 Internal Server Error - An error occurred in Entertonement's system
XML Responses
The typical XML response format is similar to the following sample.
<response>
<clip>
<id>1000</id>
<name>Sample clip</name>
</clip>
</response>
Responses are wrapped in a <response> node so that one or more objects can be returned.
JSON Responses
Typical JSON responses are of the following format.
{
"clip": {
"id": 1000,
"name": "Sample clip"
}
}
Responses are wrapped in an object and will always have an errors array which is empty if there were none.
The JSON is encoded using Rails' to_json method which replaces some HTTP characters with Unicode escape sequences. For example '<' is encoded as '\u003C'
Errors
Error responses only contain the error messages and have appropriate HTTP response codes sent as well.
XML
<errors>
<error>There was an error doing something</error>
<error>A second error doing something</error>
</errors>
JSON
{
"errors": ["there was an error doing something", "A second error doing something"]
}
