Pando Web Services

Pando provides a variety of ways to retrieve dynamically information about Pando packages using standard web technologies. This section describes available web services and related tools, from how to construct a Pando package or thumbnail URL, to retrieving structure package metadata or using our Javascript API to display custom views of package information.

The web services that Pando provides are:

Pando Package URL


Every Pando package has a unique Package URL. The file at the URL is the Pando file for the package.

Anatomy of a Package URL

The URL to any Pando package has the following structure:

http://cache.pando.com/soapservices/package.pando?id=PackageID&key=PackageKey

The URL contains two unique pieces of information needed to retrieve the full package - a Package ID and an encryption key.

The Package ID is the unique identifier of the package, and can be used with the Package Info Web Service to return the package metadata from the Pando system (package title, file names, thumbnail, number of downloads, etc.).

The encryption key is required to decrypt the contents of the package. Pando never stores encryption keys. The only way that your recipients can decrypt the package is if you give them the key, which is contained in either a Pando file or a Pando Package URL.

Getting Package URL's

One way to generate this URL is to simply find a package in the "Sent" tab of the Pando client, highlight the package and type CTRL-C (on Mac Command-C) to copy the URL to your clipboard. For more on how to get Pando Package URL's see How to get a Pando Package URL. The resultant URL will look like this:

http://cache.pando.com/soapservices/package.pando?id=5AEDE982393976A10050F2EC7C20C3C5EFDE0BBB
  &key=C51E9F2767B6747A9C9841AF7EEB9CC0E967D5B37CEC05B8C9DF310A03958AD2

What does it do?

The most common use of a Pando Package URL is to use on a web page (or email or instant message) as a link for users to click on. When a user clicks a link to a Package URL (Example Package URL link), the Pando server checks to see if the user has Pando installed (by looking for the Pando "installed" cookie). If Pando is installed, the user immediately downloads the Pando package. If Pando is not installed (or if the cookie is not set), the user will instead land on a page explaining that they need Pando in order to download the software (Example new user link).

Pando Package URL's are also used throughout the Pando Developer Toolkits, such as the Package Info Web Service, as the unique identifier of a package.

Package Thumbnail URL

The thumbnail image of a package can be accessed by retrieving it from the Package Thumbnail URL.

Anatomy of a Package Thumbnail URL

Like Package URLs, the Package Thumbnail URL is a specially structured URL, containing the Package ID:

http://cache.pando.com/soapservices/SendToWeb?action=thumbnail&id=PackageId

Example: image tag

If you know the Package ID, you can automatically generate an image tag. For example:

<img alt="Spring Street Art" title="Download Spring Street art with Pando"
   src="http://cache.pando.com/soapservices/SendToWeb?action=thumbnail
   &id=5AEDE982393976A10050F2EC7C20C3C5EFDE0BBB">

Which looks like: Spring Street Art

Example: image link

Using both the Package Thumbnail URL and the Package URL, could wrap the image in a link to the package itself, like this:

<a href="http://cache.pando.com/soapservices/package.pando?
   id=5AEDE982393976A10050F2EC7C20C3C5EFDE0BBB
   &key=C51E9F2767B6747A9C9841AF7EEB9CC0E967D5B37CEC05B8C9DF310A03958AD2">
   <img alt="Spring Street Art" title="Download Spring Street art with Pando" 
      src="http://cache.pando.com/soapservices/SendToWeb?action=thumbnail
        &id=5AEDE982393976A10050F2EC7C20C3C5EFDE0BBB"/>
</a>

Which looks like: Spring Street Art

How Pando Generates Thumbnails

For learn more about how Pando creates thumbnails, see Publish Pretty Pando Packages.

Package Info Web Service

Getting Package Info

With a given Package ID (and optionally, package key), metadata about Pando packages can be retrieved from the Pando system. Request URLs take the following form:

http://cache.pando.com/soapservices/SendToWeb?action=info&format=Format&id=PackageId&key=PackageKey

Format can be either "xml" or "json," which determines how the data you request will be returned. The information returned includes:

  • "static" package info (also stored in the package file itself)
    • package id (passed in the URL)
    • encryption key (optional; included only if passed in the URL). If the key is not provided, users cannot download the file from the Package URL, below.
    • package name
    • description
    • creation date, in RFC 822 format
    • packager name
    • thumbnail URL
    • package URL
    • total file size, in bytes
    • list of files, with count
  • "dynamic" package info (changes over time)
    • number of downloads (number of completed downloads for the torrent right now).
    • expiration date, in RFC 822 format; omitted if the torrent has infinite expiration
    • expired; true if the package has expired from Pando's servers, omitted otherwise.

Example: XML

So, for example, the XML encoded package info for a package can be retrieved from the following URL:

http://cache.pando.com/soapservices/SendToWeb?action=info&format=xml
  &id=5AEDE982393976A10050F2EC7C20C3C5EFDE0BBB
  &key=C51E9F2767B6747A9C9841AF7EEB9CC0E967D5B37CEC05B8C9DF310A03958AD2

Which returns the following result (with the "files" list trimmed -- full result here).

<?xml version="1.0"?>
<packageInfo>
	<version>1.0</version>
	<packageId>5AEDE982393976A10050F2EC7C20C3C5EFDE0BBB</packageId>
	<key>C51E9F2767B6747A9C9841AF7EEB9CC0E967D5B37CEC05B8C9DF310A03958AD2</key>
	<title>Spring Street Art</title>
	<description>
		At 11 Spring St. some of NYC's best street artists have canvassed 
		(literally) the building with art that is sprayed/painted/glued on the 
		exterior and interior walls.
	</description>
	<creationDate>Sun, 17 Dec 2006 14:06:30 -0500</creationDate>
	<packager>Yaron Samid</packager>
	<thumbnailURL>http://services.pando.com/soapservices/SendToWeb?action=thumbnail
	&id=5AEDE982393976A10050F2EC7C20C3C5EFDE0BBB</thumbnailURL>
	<packageURL>http://cache.pando.com/soapservices/Package/package.pando?
		id=5AEDE982393976A10050F2EC7C20C3C5EFDE0BBB
		&key=C51E9F2767B6747A9C9841AF7EEB9CC0E967D5B37CEC05B8C9DF310A03958AD2
	</packageURL>
	<packageSize>187249946</packageSize>
	<files num="91">
		<file name="Spring Street Art/IMG_8277.jpg" size="2196499"/>
		[... trimmed ...]
		<file name="Spring Street Art/IMG_8367.jpg"size="2071726"/>
	</files>
	<downloads>55</downloads>
	<expirationDate>Sat, 12 Dec 2026 15:42:20 -0500</expirationDate>
</packageInfo>

Example: JSON

To retrieve a JSON encoded version of the same data, we simply ask for a different format in the URL:

http://cache.pando.com/soapservices/SendToWeb?action=info&format=json
  &id=5AEDE982393976A10050F2EC7C20C3C5EFDE0BBB
  &key=C51E9F2767B6747A9C9841AF7EEB9CC0E967D5B37CEC05B8C9DF310A03958AD2

Which returns the following result (with the "files" list trimmed -- full result here).

{"version":"1.0",
"packageId":"5AEDE982393976A10050F2EC7C20C3C5EFDE0BBB",
"key":"C51E9F2767B6747A9C9841AF7EEB9CC0E967D5B37CEC05B8C9DF310A03958AD2",
"title":"Spring Street Art",
"description":"At 11 Spring St. some of NYC's best street artists have canvassed
  (literally) the building with art that is sprayed/painted/glued on
  the exterior and interior walls.",
"creationDate":"Sun, 17 Dec 2006 14:06:30 -0500",
"packager":"Yaron Samid",
"thumbnailURL":"http://services.pando.com/soapservices/SendToWeb?action=thumbnail
  &id=5AEDE982393976A10050F2EC7C20C3C5EFDE0BBB",
"packageURL":"http://cache.pando.com/soapservices/Package/package.pando
  ?id=5AEDE982393976A10050F2EC7C20C3C5EFDE0BBB
  &key=C51E9F2767B6747A9C9841AF7EEB9CC0E967D5B37CEC05B8C9DF310A03958AD2",
"packageSize":187249946,
"fileCount":91,
"files":[
  {"name":"Spring Street Art/IMG_8277.jpg","size":2196499},
  [... trimmed ...],
  {"name":"Spring Street Art/IMG_8367.jpg","size":2071726}],
"downloads":55,
"expirationDate":"Sat, 12 Dec 2026 15:42:20 -0500"}

JavaScript Access: PandoAPI.js

The Pando JavaScript API (PandoAPI.js) provides access to the Pando Web Services for JavaScript code that is running inside a web browser.

To see an example of how to use PandoAPI.js, see Custom Package Previews with PandoAPI.js.

One important limitation of the Javascript XmlHttpRequest function (a cornerstone of AJAX) is that it does not allow a script to load the contents of a file from a domain other than the one on which the script is running. There are good reasons, from a security standpoint, that this limitation exists. There are many workarounds for this for sources you trust (e.g., proxying calls on your own server). We decided to experiment with a Javascript library that allows you to retrieve metadata from packages encoded in JSON without requiring server-side code, just client-side javascript.

The Pando Javascript API library is at http://cache.pando.com/soapservices/PandoAPI.js. To use it, you need to include it in your HTML document in the <head> section: <script src="http://cache.pando.com/soapservices/PandoAPI.js" type="text/javascript"></script>

PandoAPI.toString

The Pando Javascript API has three functions. The simplest (PandoAPI.toString) simply outputs the current version of the PandoAPI and is useful for debugging. For example, 

<html>
  <head>
   <script src="http://cache.pando.com/soapservices/PandoAPI.js" type="text/javascript">
   </script>
  </head>
  <body>
   <script type="text/javascript">
     document.write(PandoAPI.toString());
   </script>
  </body>
</html>

This will output something like: PandoAPI vtrunk

PandoAPI.getPackageURL

The second function (PandoAPI.getPackageURL) is also simple. It requires the package id and key (and optionally accepts the gotPando parameter) and generates a Package URL. 

<html>
  <head>
   <script src="http://cache.pando.com/soapservices/PandoAPI.js" type="text/javascript">
   </script>
  </head>
  <body>
   <script type="text/javascript">
    document.write(PandoAPI.getPackageURL('5AEDE982393976A10050F2EC7C20C3C5EFDE0BBB',
      'C51E9F2767B6747A9C9841AF7EEB9CC0E967D5B37CEC05B8C9DF310A03958AD2'));
   </script>
  </body>
</html>
This will output the URL to the package: 
http://cache.pando.com/soapservices/Package/Package.pando?
	id=5AEDE982393976A10050F2EC7C20C3C5EFDE0BBB
	&key=C51E9F2767B6747A9C9841AF7EEB9CC0E967D5B37CEC05B8C9DF310A03958AD2
You may also set the optional gotPando parameter. By default, it is false. Setting it to true will generate a Package URL that will skip the usual "is Pando installed?" test, and simply deliver the package. For example, replacing the necessary line from the above example: 
document.write(PandoAPI.getPackageURL('5AEDE982393976A10050F2EC7C20C3C5EFDE0BBB',
  'C51E9F2767B6747A9C9841AF7EEB9CC0E967D5B37CEC05B8C9DF310A03958AD2',
  true));
This will result in a URL that looks like 
http://cache.pando.com/soapservices/Package/Package.pando?
	id=5AEDE982393976A10050F2EC7C20C3C5EFDE0BBB
	&key=C51E9F2767B6747A9C9841AF7EEB9CC0E967D5B37CEC05B8C9DF310A03958AD2&hasPando=yes

Note: When a user follows such a link, the Pando services will attempt to set the Pando "installed" cookie.

getPackageInfo

The most powerful tool provided by this API is the PandoAPI.getPackageInfo function. It accepts as parameters the package ID, a callback function and the package key (optional). When called, this function writes another <script> tag into your document that makes available the package info in JSON format, and then calls the provided callback function to process this data. This example simply writes all the available package metadata directly into the page: 
<html>
  <head>
  <script src="http://cache.pando.com/soapservices/PandoAPI.js" type="text/javascript"></script>
  </head>
  <body>
	<script type="text/javascript">
	function printPackageCallBack(packageInfo) {
 	  //print all the properties in the packageInfo object
	  for (var prop in packageInfo) 
		document.write(prop+': <em>'+packageInfo[prop]+'</em><br/>');
	}
		
	//the package id and key (replace with your own values)
	var packageId = '5AEDE982393976A10050F2EC7C20C3C5EFDE0BBB'; 	
	var packageKey = 'C51E9F2767B6747A9C9841AF7EEB9CC0E967D5B37CEC05B8C9DF310A03958AD2';

	//use the API to retrieve the package info - results are returned to the callback function
	PandoAPI.getPackageInfo(packageId,printPackageCallBack, packageKey);

	</script>

	</body>
</html>
The resultant output (with "files" trimmed) looks something like: 
version: 1.0
packageId: 5AEDE982393976A10050F2EC7C20C3C5EFDE0BBB
key: C51E9F2767B6747A9C9841AF7EEB9CC0E967D5B37CEC05B8C9DF310A03958AD2
title: Spring Street Art
description: At 11 Spring St. some of NYC's best street artists have canvassed (literally)
the building with art that is sprayed/painted/glued on the exterior and interior walls.
creationDate: Sun, 17 Dec 2006 14:06:30 -0500
packager: Yaron Samid
thumbnailURL: http://services.pando.com/soapservices/SendToWeb?action=thumbnail
  &id=5AEDE982393976A10050F2EC7C20C3C5EFDE0BBB
packageURL: http://cache.pando.com/soapservices/Package/package.pando?
  id=5AEDE982393976A10050F2EC7C20C3C5EFDE0BBB
  &key=C51E9F2767B6747A9C9841AF7EEB9CC0E967D5B37CEC05B8C9DF310A03958AD2
packageSize: 187249946
fileCount: 91
files: [object Object], ..., [object Object]
downloads: 55
expirationDate: Sat, 12 Dec 2026 15:42:20 -0500
Notice that the file metadata aren't listed. Each file is an object containing name and size properties. If we replace our callback function to just print out a file list, e.g.: 
function printPackageCallBack(packageInfo) {
  files = packageInfo['files'];
  for (var file in files)
	document.write(files[file].name +' : '+ files[file].size +' bytes<br />');
}
We get a (trimmed) list of file names, with sizes in bytes: 
Spring Street Art/IMG_8277.jpg : 2196499 bytes
Spring Street Art/IMG_8368.jpg : 2397601 bytes
Spring Street Art/IMG_8369.jpg : 2432566 bytes
  ...
Spring Street Art/IMG_8366.jpg : 2319711 bytes
Spring Street Art/IMG_8367.jpg : 2071726 bytes

Now go read Custom Package Previews with PandoAPI.js.

PandoAPI.hasPando

This method gives web sites outside of the pando.com domain limited access to the status of the pando.com "installed" cookie. It accepts a callback function as an argument. This callback function accepts one argument, which can be true or false. When you invoke PandoAPI.hasPando, it will call document.write and write a script into your page that runs the callback function with the value set to true or false. Your callback function decides what to do with this information. We recommend running this method in your page's section and then waiting until the page is fully loaded (i.e., window.onload) to make use of the results. Please see "Using PandoAPI.js Installed Cookie Check" for a detailed example.

Is Pando Installed?

Update: In most cases, the PandoAPI javascript method for detecting Pando's installed status would be preferable to this approach. Here is a detailed example using javascript.

In many cases, it's helpful to know whether a user has Pando installed or not, to determine what to display on a particular web page containing Pando downloads or channel subscriptions, for example; and to better explain to your sites visitors how to acquire Pando if they don't already have it.

The Pando "Installed" Cookie

For our own web sites, we use a browser cookie to track whether a user has Pando installed or not. This cookie gets set in a user's default browser when they install Pando, and is set to never expire. The cookie's key/name is "installed" and value is set to "yes"). Because this cookie is accessible to any pando.com URL, we can make use of it in many places. For example, when a user clicks a package URL, we look for the cookie and, if it's set, we send the user the Pando file. If it's not set, we redirect them to a page explaining how to installed Pando (example).

Unfortunately, because cookies can only be read by the domain that sets them (a good thing for security purposes), other web sites cannot tell if a user has Pando installed.

"Installed" Cookie Check Service

To get around this limitation, we've implemented a simple "installed" cookie checking service you may use to discover if your users have Pando installed. To use this service, you must redirect your users (using javascript or, preferably, a server side script) to the following URL: http://www.pando.com/installcheck/?returnURL=http://example.com/ where http://example.com is an URL on your server that can handle the resultant response.

When a user visits the above URL, the pando web server looks for the Pando "installed" cookie and redirects the user back to the specified returnURL with hasPando=yes or hasPando=no appended to the URL parameters. It is up to you to receive this response and handle it in a useful way. We recommend setting your own cookie to remember the result of this check, to minimize these redirect-heavy requests.

Caveat

It's important to note that this is an imperfect solution. If a privacy-minded user frequently clears her cookies or uses a browser other than her default, the "installed" cookie might not be set even when she has Pando installed. It is important to allow users a way around a cookie check and force the cookie to be set to cover these cases.