...
The LittleShoot client packs together support for BitTorrent, Gnutella, and LittleShoot's own super slick P2P platform (if we do say so ourselves). LittleShoot includes an HTTP server that runs on your local computer, enabling web page developers as well as standalone desktop client developers to easily interact with LittleShoot via a simple REST API. The API enables you to do things like initiate downloads, publish files, and access the available files of other users. You can do all that using JavaScript from within your own web page or using any other language in a standalone client or browser plugin.
*All requests require your API key*. Some requests also require a secret key that you'll use to create a signature for your requests so we know it's you. To request an API key and a secret key, send an e-mail to the LittleShoot team at
[email protected]. These calls are outlined in more detail at the LittleShoot OAuth page [here|http://dev.littleshoot.org:8084/x/xIAT].
Here are the REST calls you can make:
h3. Searching
LittleShoot can search Gnutella, IsoHunt, YouTube, Yahoo, and Flickr in addition to searching the LittleShoot network itself. To initiate LittleShoot searches, you can make the following call:
{quote}
http://www.littleshoot.org/api/client/search?images=on&audio=on&documents=on&applications=on&keywords=testing&flickr=on&isoHunt=on&limeWire=on&littleShoot=on&yahoo=on&youTube=on&safeSearch=on&callback=callbackFunc
{quote}
This call returns JSON of the form:
{code:title=Search Example JSON Response|borderStyle=solid}
{"guid":"e0127d6b-8336-b398-d4ba-007097747000"}
{code}
The callback argument is optional and allows the search to call an existing javascript function with JSON as an argument. If you supply a callback argument (&callback=callbackFunc), the response will look like this:
{code:title=Search Example with Callback JSON Response|borderStyle=solid}
callbackFunc({"guid":"f90335a3-629e-851b-93b1-8006fe860100"});
{code}
The return "guid" is the ID for the search, allowing you to then make calls to search results for that ID, as documented below.
h3. Search Results
To access search results, you can make the following call, for example:
{quote}
http://www.littleshoot.org/api/client/searchResults?resultsPerPage=20&pageIndex=0&images=true&video=true&audio=true&documents=true&applications=true&guid=9ef6f93f-3b09-e8a8-7282-db5610a83100&preventCache=true&callback=callbackFunc
{quote}
*Note that if you're copying this directly or clicking it directly, you'll need to use a real GUID returned from the search call above. Otherwise LittleShoot won't be able to identify the search results to access.*
h3. Downloading a Torrent File
Downloading torrents is slightly different, although we'll likely consolidate these calls in the future. To download a torrent, do the following:
{quote}
http://www.littleshoot.org/api/client/startTorrentDownload/testing?name=TEST_FILE&size=2655319&uri=http%3A%2F%2Fca.isohunt.com%2Fdownload%2F194848661%2Ftesting.torrent
{quote}
This initiates the download. You can then either make a call to list all downloads or issue the "download info" call to get data on that particular download.
h3. Downloading a non-Torrent File
To initiate a file download, simply make a request to:
{quote}
http://www.littleshoot.org/api/client/download/file_name
{quote}
There is only one required request argument: the "URI" for the file. This can be any type of URI, including the URL of a file on a web page. In that case, LittleShoot will still perform a P2P download of the file using all peers that have a copy of that file from the web site. In many cases the URI will also be a SHA-1 URN encoded in base 32. As usual, all request parameters must be URL-encoded. Here's an example of a download request for a file by its SHA-1 URN:
{quote}
http://www.littleshoot.org/api/client/download/ls_jar.jar?uri=urn%3Asha1%3AUFVYLBEOKFSPLJMP2SODGJN3ERDETI72
{quote}
The response is the file itself, as in the file is delivered in the body of the HTTP response, just as it normally would be.
h3. Listing Data for a Single Download
To get data for single download, you just need the URI you used to initiate the download originally. You can call, for example:
{quote}
http://www.littleshoot.org/api/client/downloadInfo?uri=http%3A%2F%2Fca.isohunt.com%2Fdownload%2F194848661%2Ftesting.torrent
{quote}
You'll get a result with detailed information about the download, as follows. Note that to continually update the download speed graphically, for example, you'll want to continually make this call every couple of seconds or whatever you prefer.
{code:title=Single Download Info JSON Response|borderStyle=solid}
{"total":1,"payloadUploadRate":0,"downloadRate":143,"totalPayloadUploadBytes":0,
"downloads":[
{"id":"1000179647","numFiles":1,
"title":"Electrician\'s Troubleshooting and Testing Pocket Guide/Electrician\'s Troubleshooting and Testing Pocket Guide.rar",
"lastModified":1.299730443176E12,
"maxByte":2655324,"downloadSource":2,"torrentState":5,
"path":"/Users/afisk/shared/downloads","streamable":false,
"uri":"http://ca.isohunt.com/download/194848661/testing.torrent",
"downloadStatus":200,"size":2655324}
],
"historicUploadBytes":6.321722735E9,
"payloadDownloadRate":0,
"historicDownloadBytes":1.8320230654E10,
"numDownloads":1,
"numPeers":0,
"totalDownloadBytes":2965931,
"totalPayloadDownloadBytes":2788642,
"capabilities":[1],
"downloadDir":"/Users/afisk/shared/downloads",
"uploadRate":379,
"totalUploadBytes":192835}
{code}
h3. Listing All Downloads
To list all active downloads, you can call:
{quote}
http://www.littleshoot.org/api/client/downloads?pageIndex=0&resultsPerPage=10&key=YOUR_API_KEY
{quote}
Here's an example response:
{code:title=Current Downloads Example JSON Response|borderStyle=solid}
{"total":1,"payloadUploadRate":0,"downloadRate":143360.40625,"totalPayloadUploadBytes":0,
"downloads":
[
{"numFiles":1,
"lastModified":1.286566451372E12,
"maxByte":0,
"downloadNumSources":2,
"downloadBytesRead":1818624,
"uri":"http://build.eclipse.org/technology/phoenix/torrents/java/eclipse-java-helios-SR1-macosx-cocoa-x86_64.tar.gz.torrent",
"downloadStatus":2,
"size":1.03430976E8,
"id":"2062319294",
"title":"eclipse-java-helios-SR1-macosx-cocoa-x86_64.tar.gz",
"downloadSpeed":131.08203125,
"torrentState":3,
"downloadSource":2,
"path":"/Users/afisk/shared/downloads",
"streamable":false,
"timeRemaining":"12 mins, 37 secs"}
],
"historicUploadBytes":1.893441393E9,
"payloadDownloadRate":143057.203125,
"historicDownloadBytes":2.566808089E9,
"numDownloads":1,
"numPeers":2,
"totalDownloadBytes":1821084,
"totalPayloadDownloadBytes":1818624,
"capabilities":[1],
"downloadDir":"/Users/afisk/shared/downloads",
"uploadRate":4181.5,
"totalUploadBytes":3752}
{code}
h3. Listing Files
After reading the downloading example above, you might be wondering how you would ever know the SHA-1 URN for a file. This is how. The request takes three required arguments:
# instanceId -- The ID of the actual machine you wish to list the files for
# pageIndex -- The page you wish to view, starting with 0
# resultsPerPage -- The number of results to show per page
Here's an example request:
{quote}
http://www.littleshoot.org/api/fileListing?instanceId=1183733614&pageIndex=0&resultsPerPage=5
{quote}
Here's an example response:
{code:title=File Listing Example JSON Response|borderStyle=solid}
{ "results" : [ { "averageRating" : 0.0,
"country" : "US",
"downloaded" : false,
"instanceId" : 1183733614,
"instanceOnline" : true,
"language" : "en",
"mediaType" : "document",
"mimeType" : "application/octet-stream",
"numDownloads" : 10,
"numRatings" : 0,
"permission" : 0,
"publishTime" : "2010-05-16 15:47:25",
"sha1" : "urn:sha1:UAYXKE637D7OM3YPWW7EKO776WRMUJQE",
"size" : 2674,
"tags" : [ ],
"takenDown" : false,
"title" : "HttpHandlerExceptionResolver.java",
"uri" : "urn:sha1:UAYXKE637D7OM3YPWW7EKO776WRMUJQE"
},
{ "averageRating" : 0.0,
"country" : "US",
"downloaded" : false,
"instanceId" : 1183733614,
"instanceOnline" : true,
"language" : "en",
"mediaType" : "document",
"mimeType" : "application/octet-stream",
"numDownloads" : 213,
"numRatings" : 0,
"permission" : 0,
"publishTime" : "2010-05-16 15:54:53",
"sha1" : "urn:sha1:F3GEDJXJR65UM2UD3Q6DW2K24UALP5DA",
"size" : 596,
"tags" : [ ],
"takenDown" : false,
"title" : "HttpServer.java",
"uri" : "urn:sha1:F3GEDJXJR65UM2UD3Q6DW2K24UALP5DA"
},
],
"totalResults" : 61,
"totalResultsFormatted" : 61
}
{code}
h3. Publishing a File
To publish a file, you similarly make a call to the LittleShoot server running locally. The basic call is similar:
{quote}
http://www.littleshoot.org/api/client/publishFile?
{quote}
File publishing is slightly more sensitive than most calls, however, as it's making a file available on a user's computer for public downloading. These requests therefore need to be signed. The system for this is modeled after the way Amazon's web services sign requests. Each LittleShoot API user has both an ID and a secret key. The ID allows us to identify the publisher on our servers, and the secret key is used to create a secure signature for the request. When the request comes in on our servers, we look up the secret key using the publishers ID and verify that the signature for that request matches the signature we calculate.
h3. Initiating an unreliable data session, such as a voice or video call
To initiate a call, make the following request:
{quote}
http://www.littleshoot.org/api/client/startCall?uri=URI_OF_CALLEE
{quote}
That call will initiate the session with the remote host and will return JSON data specifying the ID of the call, as in:
{code}
{id: ROE431FLJS}
{code}
h3. Sending call data
Once the call is initiated, you can then issue an *HTTP POST* request to start sending data to the remote peer. You simply keep the HTTP connection open and continue to send whatever data you like in the *HTTP POST* body. Note that you can't test this simply by clicking on the link below in your browser, as that will attempt an unsupported HTTP GET request.
{quote}
http://www.littleshoot.org/api/client/writeCallData?id=ID_OF_CALL
{quote}
h3. Reading call data
Once the call is initiated, you can similarly read call data from the remote host with the readCallData method.You will want to keep the HTTP connection open for the duration of the call.
{quote}
http://www.littleshoot.org/api/client/readCallData?id=ID_OF_CALL