View source

===Drivecast API Specification===

Drivecast provides a REST API at the url: <nowiki>https://drivecast.eu/api/1.0/<RESOURCE></nowiki><br \>
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)<br\>
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<br \>
<br \>

=====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<br \>

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:<br\>
''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.''<br\>
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:<br\>
 <strike><nowiki>curl --user username:password "https://drivecast.eu/api/1.0/playlist/my playlist?apikey=ABCDEFGHILMNOPQ"</nowiki></strike> 
The correct form is:
 <nowiki>curl --user username:password "https://drivecast.eu/api/1.0/playlist/my%20playlist?apikey=ABCDEFGHILMNOPQ"</nowiki>