LittleShoot Client API - adamfisk/littleshoot-client GitHub Wiki

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.

Here are the REST calls you can make:

Logging In

To login to the LittleShoot signaling server, you can make the following call. Note that this call can only be make with HTTP POST requests.

http://www.littleshoot.org/api/client/login?username=your_user_name&password=your_password&host=your_xmpp_host

You can test this with, for example:

curl -d "username=7777777&password=test&host=talk.google.com" http://www.littleshoot.org/api/client/login

If the call succeeds, the response will be as follows, for example. This is the result of logging in with a user name of "7777777":

{"success":true, 
"uri":sip:[email protected]}

Otherwise, you'll see:

{"reason":"'username' and 'password' arguments required","success":false}

Downloading a File

To initiate a file download, simply make a request to:

http://www.littleshoot.org/api/client/download/file_name

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:

http://www.littleshoot.org/api/client/download/ls_jar.jar?uri=urn%3Asha1%3AUFVYLBEOKFSPLJMP2SODGJN3ERDETI72

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.

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:

http://www.littleshoot.org/api/client/startTorrentDownload/testing?name=TEST_FILE&size=2655319&uri=http%3A%2F%2Fca.isohunt.com%2Fdownload%2F194848661%2Ftesting.torrent

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.

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:

http://www.littleshoot.org/api/client/downloadInfo?uri=http%3A%2F%2Fca.isohunt.com%2Fdownload%2F194848661%2Ftesting.torrent

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.

{"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}

Listing All Downloads

To list all active downloads, you can call:

http://www.littleshoot.org/api/client/downloads?pageIndex=0&resultsPerPage=10&key=YOUR_API_KEY

Here's an example response:

{"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}

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:

http://www.littleshoot.org/api/fileListing?instanceId=1183733614&pageIndex=0&resultsPerPage=5

Here's an example response:

{ "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
}

Publishing a File

To publish a file, you similarly make a call to the LittleShoot server running locally. The basic call is similar:

http://www.littleshoot.org/api/client/publishFile?

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.

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:

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

This call returns JSON of the form:

{"guid":"e0127d6b-8336-b398-d4ba-007097747000"}

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:

callbackFunc({"guid":"f90335a3-629e-851b-93b1-8006fe860100"});

The return "guid" is the ID for the search, allowing you to then make calls to search results for that ID, as documented below.

Search Results

To access search results, you can make the following call, for example:

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

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.

Initiating an unreliable data session, such as a voice or video call

To initiate a call, make the following request:

http://www.littleshoot.org/api/client/startCall?uri=URI_OF_CALLEE

For example, to initiate a call to user "7777777" from the login example, you would do the following (URL encoded of course):

http://www.littleshoot.org/api/client/startCall?uri=sip%3A7777777%40lastbamboo.org

To test with curl, this is just:

curl http://www.littleshoot.org/api/client/startCall?uri=sip%3A7777777%40lastbamboo.org

That call will initiate the session with the remote host and will return JSON data specifying the ID of the call, as in:

{"id":"e1dd32b5-792a-4f2c-882f-d0964cfd7c5b"}

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.

http://www.littleshoot.org/api/client/writeCallData?id=e1dd32b5-792a-4f2c-882f-d0964cfd7c5b

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.

http://www.littleshoot.org/api/client/readCallData?id=e1dd32b5-792a-4f2c-882f-d0964cfd7c5b

Checking for calls

To maintain two-way calling, you'll also have to periodically check for current calls.

http://www.littleshoot.org/api/client/allCalls

This will give you the IDs of all the open calls and their status. You'll typically only call this to check for incoming calls to you since you already know the IDs of calls you've initiated.