Drivecast API 2.0

From DriveCast Wiki

(Redirected from Drivecast API)
Jump to: navigation, search

Contents

Drivecast API Specification

The Drivecast API is conformed to the design principles of Representational State Transfer (REST).
The API supports the following data formats: JSON, XML and PLIST.


The Drivecast API is accessible from the url:

https://drivecast.eu/api/2.0/<RESOURCE>

Where <RESOURCE> is the structured string representing the resource you need to access.


Methods

The API supports the following HTTP methods to send and receive Drivecast data.

Each method determine the action perfomed.

Supported methods are:

  • GET (read)
  • POST (create)
  • DELETE (delete)
  • PUT (modify)


An example:

RESTful Drivecast API HTTP methods
Resource GET PUT POST DELETE
Resource URI such as http://drivecast.eu/podcast/<UID> Retrieve the metadata associated to the podcast, like the title, author, description and URL. Update the metadata associated to the podcast item. (This needs to send an object as the request body) Insert a new podcast. (This needs to send an object as the request body) Delete a podcast on the base of his UID.

For client platforms that do not support the full set of http methods, the DELETE call can be surrogated by a GET with the added parameter &getcommand=DELETE


Resources

The resources that can be accessed are the following:

dcst - Calculates the dcst shortcut for recording or podcast.

device - Returns the user device list, delete or create a device.

feed - Returns the user feeds.

library - Returns all the items, delete or modify one.

playlist - Returns the user playlist list, the content of the give one, delete or create a playlist.

playposition - Return the latest play position of a library item or set it.

podcast - Returns all the podcast, delete or modify one.

radio - Returns the radios and radio detail.

recording - Returns all the recording, delete or modify one.

thumbnail - Returns all the image associated to an object.

API_2.0_upload|upload - Upload in 2 step the multimedia file to drivecast. REMOVED after the introduction of third party cloud storage (Dropbox, Box.net)


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 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 based on the API, can access to the different resources and do different actions on them. The results are returned by default in JSON format, other formats (xml and plist) can be asked specifying it into the "fmt" url variable:

?fmt=json (default)     ?fmt=xml     ?fmt=plist


Error Codes

The error code is 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>
...


Encoding

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 (or equivalent method), some library do it automatically, others does not. For example this curl command is wrong:

curl --user username:password "https://drivecast.eu/api/2.0/playlist/my playlist?apikey=ABCDEFGHILMNOPQ" 

While the correct form is:

curl --user username:password "https://drivecast.eu/api/2.0/playlist/my%20playlist?apikey=ABCDEFGHILMNOPQ"
Personal tools