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
http://example.com/resources

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
http://example.com/resources/12345

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)

Accept

Result

application/json

API response in JSON format (RFC 4627)

application/xml

API response in XML format (RFC 3023)

"Anything Else"

415 - Unsupported Media Type

Extension

An extension (like a file extension) can be added to the URI to force the service to return the API response in the desired format.

Extension

Result

.json

API response in JSON format (RFC 4627)

.xml

API response in XML format (RFC 3023)

"Anything Else"

415 - Unsupported Media Type

Help

IceTV can answer questions relating to integrating this API into your application via the email address developer@icetv.com.au