API Specification.JSON
Overview
The Revver JSON API supports on a subset of functions provided by the full XML-RPC API. It is well suited for applications that use heavy javascript or AJAX, and/or Flash, but not appropriate for applications that need to update or add content to Revver. For those functions, you will need to use XML-RPC for security reasons.
Description
The Revver JSON API utilizes "open" methods. They are identical to the XML-RPC methods of the same name, except that there is no user access restriction, or namespace. Open methods allow users to have "read-only" access to the API for content that is public only. For this reason, you cannot use the JSON API to get statistics other than overall views.
Because of the restrictions of AJAX calling remote servers, Revver maintains a javascript library called revverAPI.js that can be used to access the JSON API via JavaScript. This file when called remotely contains all the necessary logic to access the Revver JSON API.
The revverAPI.js file is located at: http://widget.revver.com/js/lib/revverAPI.js. In order to use it, simply include it in the HEAD of your HTML document.
i.e.<head>
<script type="text/javascript" src="http://widget.revver.com/js/lib/revverAPI.js">
</script>
</head>
Usage
The revverAPI constructor is called "Revver.API". You call it as follows:
Once called, the Revver.API object can be used one of three ways:
| single resultset FUNCTION is one of "collection.get" or "video.get" |
api.FUNCTION(id, [returns], {onSuccess: callbackFunc} );
|
|---|---|
| multiple results FUNCTION is one of "open.collection.collect", "open.video.find" or "open.video.find" |
Note: collection.collect takes single collection_id rather than query as indicated
api.FUNCTION({query}, [returns], {options}, {onSuccess: callbackFunc} );
|
| paged results FUNCTION is one of "open.collection.collect", "open.video.find" or "open.video.find" |
Note: collection.collect takes single collection_id rather than query as indicated
pager = api.FUNCTION.pager({query}, [returns], {options});
pager.page(limit, offset, {onSuccess: callbackFunc} );
|
The revverAPI.js file enables users to create "callbacks" to handle the data that is returned from the API directly. Behind the scenes what happens is that the javascript function calls are converted to JSON and passed as a GET request to the JSON API server, which in turn sends back a JSON object to the RevverJSONClient. The client then passes the JSON result back to a callback function for processing. If you want to explore the RevverJSONClient.js file in more detail, please feel free. If you decide to change it, or do something else cool using it,
Code Sample
click here to see a demo of the example below.
For some real-world examples, see the Example Code for JSON.
<script type="text/javascript">
var api = new Revver.API('https://api.revver.com/json/1.0');
function jsonExample() {
api.open.collection.get(593, ['name', 'owner', 'description','count'], {
onSuccess: function (result) {
video = result;
alert("name:" + video.name +
"\n# of videos:" + video.count +
"\nowner: " + video.owner +
"\ndescription: " + video.description );
} });
}
</script>