Javascript Library
From DriveCast Wiki
Contents |
Introduction
This Javascript library allows to make direct requests to the Drivecast API 2.0 (and Drivecast API 1.0 that we don't recommend to use).
The purpose is to enable developers to implement a Drivecast GUI inside a web application using simple javascript functions.
In order to work with the Drivecast API, you need to create an account and to request an API Key in the Developer section of your Drivecast account.
The start point of your development is the Drivecast API Javascript Library.
Download the library source here: http://beta.drivecast.eu/lib/1.0/DrivecastAPI.js (right click and Save as...)
It makes available an object, called Drivecast that contains few important functions.
Usage
The use of the Drivecast API Javascript Library is really simple.
Include the Drivecast API Javascript Library into your html page
<script type="text/javascript" src="http://beta.drivecast.eu/lib/1.0/DrivecastAPI.js" charset="utf-8"></script>
Create an instance of the object:
var d = new Drivecast();
Set the APIKey
d.setAPIkey("APIkey");
Set the AuthCode
d.setAuthorizationCode( "user" , "password");
Set the API version (optional). If the API version is not specified, the 2.0 version will be automatically used:
d.setAPIversion("api version");
The "api version" possible values are:
- 1.0
- 2.0 (we recommend to use this version)
In order to make a request use:
d.makeRequest("resource","action"[,options]);
Resources
The resources available are those of the Drivecast API
"feed" "playlist" "library" "radio" "recording" "podcast" "device" (API 2.0 only) "dcst" (API 2.0 only) "myMedia" (deprecated)
Actions
The possible actions are
"read" - to get information about a resource "create" - to insert a new element "modify" - to edit an element "delete" - to delete an element
To know which actions are available according to a specific resource, read the Drivecast API 2.0 documentation.
Examples
Call the makeRequest function to request the feed to the Drivecast API
var d = new Drivecast();
d.setAuthorizationCode( "user" , "password");
d.makeRequest("feed", "read", {
onFinish : function(obj,code,desc){
alert("feed object: "+obj.feedURL+" Code: "+code+" Desc: "+desc)
},
onError : function(code,desc){
alert("feed request ERROR: Code: "+code+" Desc: "+desc)
}
});
To modify an existing library item:
var dli = new DrivecastLibraryItem("modified author","modified title","modified description");
d.makeRequest("library/uid","modify", {
object : dli,
onFinish: function(code,desc){
alert("Library Modified: Code "+code+" Desc: "+desc);
}
onError: function(code,desc){
alert("Library Modified ERROR: Code "+code+" Desc: "+desc);
}
});
Create a podcast:
var dp = new DrivecastPodcast("podcast url","title","description");
d.makeRequest("podcast", "create", {
object: dp,
onFinish: function(code,desc){
alert("Podcast created: Code "+code+" Desc: "+desc)
},
onError: function(codee,desce){
alert("Podcast creation Error: Code "+code+" Desc: "+desc)
}
});
Remember to close the script tag
</script>
makeRequest options
The possible options are:
object an instance of the provided objects (see below)
onFinish the callback function triggered when the request is completed successfully
arguments returned: an Object (see N.B. below), the HTTP code, the HTTP description
onError the callback function triggered when an error occurs or when the API request is not well-formed
arguments returned: the HTTP code, the HTTP description
N.B. the onFinish event returns the Object ONLY if you perform a "read" action
Object returned API 2.0
If the Object is returned (only if you perform the "read" action) the variables that contains are different according to the resource requested.
Here is the list of the variables provided, using the Drivecast API 2.0 (you can find them on the Drivecast API 2.0 documentation, but are reported here for facility):
Resource Requested Object variables
"feed" obj.feedURL - the rss feed of the user
obj.opmlURL - the opml list containing the users podcasts
obj.recsURL - an xml list containing the users recordings
......................................................................................
"playlist" obj.elements[index] - an array of playlist items
obj.elements[index].name - the name of the playlist
obj.elements[index].uid[index] - an array containing the uid of the playlist's elements
......................................................................................
"playlist/PLAYLIST_NAME" obj.elements[0] - an array of item UIDs contained in the playlist
obj.elements[0].name - the name of the playlist
obj.elements[0].uid[index] - an array containing the uid of the playlist's elements
......................................................................................
"device" obj.device[index] - an array of device name
......................................................................................
"device/DEVICE_NAME" no object returned
......................................................................................
"library" obj.elements[index] - an array of item UIDs of the library
......................................................................................
"library/UID" obj.elements[index].author
obj.elements[index].title
obj.elements[index].description
obj.elements[index].playlist_string[index] - an array of the playlist names, with whom the item is associated
obj.elements[index].enclosure_url - the url of the item
obj.elements[index].length - the size of the item
obj.elements[index].type - the content type of the file
......................................................................................
"radio" obj.elements[index] - the array of all the available radios
obj.elements[index].uid
obj.elements[index].radio_name
obj.elements[index].country_code
obj.elements[index].language_code
......................................................................................
"radio/UID" obj.elements[0] - the array of all the available radios
obj.elements[0].uid
obj.elements[0].radio_name
obj.elements[0].country_code
obj.elements[0].language_code
......................................................................................
"recording" obj.elements[index] - an array of recording items
obj.elements[index].uid
obj.elements[index].title
obj.elements[index].radio_name
obj.elements[index].from_time
obj.elements[index].to_time
obj.elements[index].rectype
obj.elements[index].repeat
......................................................................................
"recording/UID" obj.elements[0] - an array of recording items
obj.elements[0].uid
obj.elements[0].title
obj.elements[0].radio_name
obj.elements[0].from_time
obj.elements[0].to_time
obj.elements[0].rectype
obj.elements[0].repeat
......................................................................................
"podcast" obj.elements[index] - an array of available podcast items
obj.elements[index].uid
obj.elements[index].title
obj.elements[index].description
obj.elements[index].subscription_type
obj.elements[index].feed
......................................................................................
"podcast/UID" obj.elements[0] - an array of available podcast items
obj.elements[0].uid
obj.elements[0].title
obj.elements[0].description
obj.elements[0].subscription_type
obj.elements[0].feed
......................................................................................
"dcst" obj.elements[0].dcst
Object returned API 1.0
If the Object is returned (only if you perform the "read" action) the variables that contains are different according to the resource requested.
Here is the list of the variables provided, using the Drivecast API 1.0 (you can find them on the Drivecast API 1.0 documentation, but are reported here for facility):
Resource Requested Object variables
"feed" obj.feedURL - the feed url
......................................................................................
"playlist" obj.playlist[index] - an array of playlist names
......................................................................................
"playlist/PLAYLIST_NAME" obj.uid[index] - an array of item UIDs contained in the playlist
......................................................................................
"library" obj.uid[index] - an array of item UIDs of the library
......................................................................................
"library/UID" obj.author
obj.title
obj.description
obj.playlist_string[index] - an array of the playlist names, with whom the item is associated
obj.enclosure_url - the url of the item
obj.length - the size of the item
obj.type - the content type of the file
......................................................................................
"radio" obj.radio[index] - the array of all the available radios
obj.radio[index].uid
obj.radio[index].radio_name
obj.radio[index].country_code
obj.radio[index].language_code
......................................................................................
"radio/UID" obj.radio[index].radio_idname
obj.radio[index].radio_fullname
obj.radio[index].country_code
obj.radio[index].language_code
obj.radio[index].timezone
obj.radio[index].homepage
obj.radio[index].schedule
obj.radio[index].logo
obj.radio[index].cloud_recordable
obj.radio[index].usb_recordable
......................................................................................
"recording" obj.uid[index] - an array of recording UIDs
......................................................................................
"recording/UID" obj.title
obj.radio_name
obj.from_time
obj.to_time
obj.rectype
......................................................................................
"podcast" obj.uid[index] - an array of the podcast UIDs
......................................................................................
"podcast/UID" obj.title
obj.description
......................................................................................
"myMedia" (deprecated) obj.item[index] - an array of items
obj.item[index].title
obj.item[index].author
obj.item[index].description
obj.item[index].convert
obj.item[index].ccgext
obj.item[index].playlists_string
obj.item[index].pubDate
obj.item[index].uid
obj.item[index].guid
obj.item[index].enclosure_attr.url
obj.item[index].enclosure_attr.length
obj.item[index].enclosure_attr.type
Drivecast Item Objects
These are the objects that you can create and pass to the makeRequest function as "object" option.
new DrivecastLibraryItem("author", "title", "description");
new DrivecastRecording("radioID", "timezone_used", "from_time", "to_time", "repeat", "rectype", "keep", "title");
new DrivecastPodcast("podcast_url", "podcast_title", "podcast_description");
Example
var dp = new DrivecastPodcast("http://rss.cnn.com/services/podcasting/newscast/rss.xml", "CNN", "CNN News Podcast");
d.makeRequest("podcast","create",{ object: dp });
