Drivecast API 1.0
From DriveCast Wiki
Contents |
Drivecast API Specification
Drivecast provides a REST API at the url: https://drivecast.eu/api/1.0/<RESOURCE>
Where RESOURCE is the structured string representing the resource you are working
with the REST method of read (GET), create (POST), delete (DELETE) or modify (PUT)
The resource that can be accessed and worked are the following:
feed - Returns the user feed.
playlist - Returns the user playlist list, the content of the give one, delete or create a playlist.
device - Returns the user device list, delete or create a device.
library - Returns all the items, delete or modify one
radio - Returns the radios and radio detail
recording - Returns all the recording, delete or modify one
podcast - Returns all the podcast, delete or modify one
thumbnail - Returns all the image associated to an object
Authentication
User and Password
The user access credential (username and password) are present in every API call as part of the HTTP HEADER of the request, according to the basic authentication criteria as defined by RFC2617, an example of the header line is:
Authorization: Basic ZnJlZDp0aGF0cyBtZQ==
Where the ending string is the pair <username>:<password> coded base64
Drivecast API Key
In order to create your application, you have to request your API Key (in the Software -> Developers section of your Drivecast account). Then put it in the HTTP HEADER User-Agent field. An example is:
User-Agent: DriveCast apikey=ABCDEFGHILMNOPQ
Where the string after "ABCDEFGHILMNOPQ" is your API Key
Alternatively it is possible to send it within the request url, using this format:
?apikey=ABCDEFGHILMNOPQ
If you specify other options:
?fmt=json&apikey=ABCDEFGHILMNOPQ
Formats
Client applications using the API can access the different resources and do different action on them. The results are returned by default in JSON format, other formats (xml and plist) can be asked appending to the request the switch:
?fmt=json (default) ?fmt=xml ?fmt=plist
Error Codes
The error code are mainly carried by the returned HTTP status code. For developer convenience they are also included at the beginning of the returned data in a format similar to:
{"statuscode":"200",
"statusdesc":"OK"
...
<?xml version="1.0" encoding="UTF-8"?> <statuscode>200</statuscode> <statusdesc>OK</statusdesc> ...
<?xml version="1.0" encoding="UTF-8"?> <plist> <dict> <key>statuscode</key> <string>200</string> <key>statusdesc</key> <string>OK</string> ...
Spaces
Since the HTTP protocol specifies that:
A request line has three parts, separated by spaces: a method name, the local path of the requested resource, and the version of HTTP being used.
Spaces inside a resource name MUST always be coded as %20 (o equivalent method), some library do it automatically, some dosn't. For example this curl command is wrong:
curl --user username:password "https://drivecast.eu/api/1.0/playlist/my playlist?apikey=ABCDEFGHILMNOPQ"
The correct form is:
curl --user username:password "https://drivecast.eu/api/1.0/playlist/my%20playlist?apikey=ABCDEFGHILMNOPQ"
