Home
Overview
This site describes the IceTV API specification and usage.
Included in the documentation are details for all of the available API calls, common use cases, and suggestions for optimal usage.
The IceTV API will follow the REST model
Resource |
GET |
PUT |
POST |
DELETE |
Collection URI, such as |
List the URIs and perhaps other details of the collection's members. |
Replace the entire collection with another collection. |
Create a new entry in the collection. The new entry's URL is assigned automatically and is usually returned by the operation. |
Delete the entire collection. |
Element URI, such as |
Retrieve a representation of the addressed member of the collection, expressed in an appropriate Internet media type. |
Update the addressed member of the collection. |
Treat the addressed member as a collection in its own right and create a new entry in it. |
Delete the addressed member of the collection. |
Information on the application making the requests will be part of the URL for all requests. We will assign an api-key to all users of the service that will uniquely identify their application, you can request an api-key by emailing IceTV at developer@icetv.com.au with the details of the application and a link to the application you are developing for. The application version number will also be included, these allow greater control of which clients will be accepted in the event of a poorly written client.
The URL will look like
https:
//api.icetv.com.au/ENTITY?api_key=API_KEY&application_version=APP_VERSION
Where
Parameter |
Description |
API_KEY |
IceTV generated unique API key, used to identify a client application |
APP_VERSION |
Client application version number, may be anything that is meaningful to the client |
ENTITY |
The entity that the API call refers to, i.e. devices, shows, series etc |
Authentication
Once a user has gone through the login process for the API they will have a token, this along with the email address must be included for all entities except for the regions entity and the login entity
Adding these the URL will now look like:
https:
//api.icetv.com.au/ENTITY?api_key=API_KEY&application_version=APP_VERSION&email_address=EMAIL_ADDRESS&token=TOKEN
WHERE
Parameter |
Description |
EMAIL_ADDRESS |
Email address of the IceTV user |
TOKEN |
Token that was generated for the IceTV user as part of the login process |
HTTP Status Codes
We will use HTTP Status codes to convey information about the result of each request, the API spec will contain more information about the use of the codes, we expect to use the following
Code |
Name |
Description |
200 |
OK |
The request was successfully completed. |
201 |
Created |
The request was completed and resulted in the creation of a new resource, check the Location response header for the new URI. |
401 |
Unauthorized |
The request was not authenticated. |
404 |
Not Found |
The requested resource does not exist. |
405 |
Method Not Allowed |
The requested operation is not appropriate, ie DELETE sent to a "read-only" URI. |
406 |
Not Acceptable |
The request contained incorrect parameters or information. |
415 |
Unsupported Media Type |
The request contained an unsupported document type. |
503 |
Service Unavailable |
The server is too busy to service this request or you are hitting the server too frequently. |
Error Handling
In the event of an error, signified by a 406 status code, an "Errors" document will be returned (the API will include a list of of error_codes and their meanings).
If there are multiple errors to be reported they are shown up to the first error that would otherwise cause a series of dependent errors to be generated, i.e. an error in a field that is referred to by subsequent fields would result in the first field being flagged while subsequent ones are dropped.
A sample Errors document appears below
<errors>
<error_code="12345" error_msg="Something bad happened">
</errors>
Formats
The API will support two I/O formats, XML and JSON. It will be possible to specify the format of the input and output via two methods
HTTP Accept header
This is a contentious subject and due to differences in browsers handling of this header we will take a practical, if somewhat unusual approach.
(for more info on why this is tricky Unacceptable Browser HTTP Accept Headers)
Help
IceTV can answer questions relating to integrating this API into your application via the email address developer@icetv.com.au