The DivShare API

The DivShare API, or application programming interface, allows web developers to interact with DivShare's database to receive info and upload files for use in their own applications. If you're a web programmer, this page is for you — if not, check out some of our other integration options.

Last updated on October 15, 2009

Quick Start

We've developed a client library that works in PHP 4, and we encourage you to submit your own libraries in other languages, which we'll post here for everyone to use. Download the client library ZIP here:

• PHP 4 Client Library

For questions and discussion, check out the API Google Group or drop us a support e-mail.

Introduction

The DivShare API is made up of two main elements — the first is a script on our server that, when you send it the proper queries, will return information about DivShare files and users. This response comes in the form of XML, and should conform to REST standards. The second part of the API is the script that runs on your server, which sends queries to our script and then interprets the response. This is called a client library, and the code will vary depending on the language you use on your server. For the purposes of this documentation, we'll focus on the PHP 4 client created by our own developers.

With our API, you can:
• Log in to a user's account.
• Get info on the user's files
• Get info on the user's account
• Upload new files to the account

To use it, you'll need:
• Intermediate web programming knowledge
• An API key and secret key, which you can generate on your My Account page

With the API, you can create:
• Apps and widgets to manage DivShare accounts
• Media sharing sites that use DivShare as the backend
• Your own embedded video, audio, slideshow and document solution, built right into your site

Setting up the API client

In our PHP example, the API client is simply a PHP class that you include in your script and then instantiate as an object. Once you've created that object, you can use its functions to easily send data to and retrieve data from the DivShare server. Grab the client library from the Quick Start section, and add it to your script with this code:

$my_api_key = [API KEY];
$my_secret = [SECRET KEY];

require 'ds_client_library.php'; // replace this with the actual path to your library
$ds = new divshare_api($my_api_key, $my_secret);

You can generate an API key and secret key on your My Account page. Use a different key for each application you develop, because we may add identifying info to each key (Name and URL of the app, for example) in the future.

You now have a divshare_api object called $ds, which you can use throughout the page. Sending your API key and secret key as arguments is necessary to identify your application to the server. For security, you should never send your secret key over the web — it should only reside in your server-side code. Now, let's make our first API call.

Logging in

Method: login

To get any useful information from the server, you'll need to log in to a user's account. Depending on the purpose of your application, you may log in directly to your backend account, or you may have users submit their information to you through a form. If you do accept user login details through your site, you may not retain this data in any way, and you must explicitly state this policy on the login form.

$email = [E-MAIL];
$password = [PASSWORD];
$api_session_key = $ds->login($email, $password);
if ($api_session_key) {
// You're logged in!
} else {
// There was a login error
}

On success, the API will return an API session key, which is unique to this user and this application. You will need this for further API calls, and you can use it to access a user's account on future pages without sending the e-mail address and password again. If you're building a client in another language, here's the server response you can expect:

<?xml version="1.0" encoding="UTF-8"?>
<response status="1">
<api_session_key>123-abcdefghijkl</api_session_key>
</response>

We'll be building in better error handling as we continue development, but here's the current login error response:

<?xml version="1.0" encoding="UTF-8"?>
<response status="0">
<error>Sorry, your e-mail and password do not match.</error>
</response>

Future Logins with the Session Key

Once you've logged in, you can call API methods within that script immediately. You should store your session key (in a PHP session, for example) so that each page the user visits can access the user's account without logging in again. To log in with your existing session key, just instantiate your PHP object with the session key as the third argument.

$ds = new divshare_api($api_key, $secret, $session_key);

You shouldn't store a user's session key for any longer than he or she is engaged with your application. We'll add more information about session key expiration as we continue development.

Getting User Info

Method: get_user_info

This is the most basic request you can make to the API. No parameters are necessary (since you're already logged in), and it will respond with an array that contains your user's first name and e-mail address. We may add more to this response as we continue development.

$user_info = $ds->get_user_info();

Getting a List of the User's Files

Method: get_user_files

This will return an array of the files assigned to a user's account, with the most recently uploaded files listed first. You can send two paramters, limit and offset, which work just like they do in a SQL query. The limit sets the maximum number of records to return, and the offset sets the start record (that is, an offset of 10 means the 11th record is the first in the returned list). Both are optional and must be integers.

$files = $ds->get_user_files($limit, $offset);

Getting a List of the Files in a Folder

Method: get_folder_files

This method returns file info in the same format as get_user_files. The required parameter is folder_id, which you can retrieve from the file info of any file that is inside a folder. You only have access to folders created by the logged-in user. We'll soon be adding a get_folder_list method to return a more easily accessible list of folders in the user's account. This method also takes the limit and offset parameters described above.

$files = $ds->get_folder_files($folder_id, $limit, $offset);

Getting Specific Files

Method: get_files

This method returns info on as many specific files as you want. The required parameter (in PHP) is an array of one or more file IDs. These are actually sent to the server as a comma-separated string, so be sure to use that format if you're working in a different language. With this method, you can access files that don't belong to the logged-in user (if you know the file ID), but only if they're not password-protected.

$files = $ds->get_files(array($file_id_1, $file_id_2)); // works for unlimited files

Downloading and Embedding Files

Once you've got your file info, it's time to put it to good use. Each of the file methods returns a file_id element, which you can plug into the below templates to create download links and embed code.

Download / Viewing Pages:

Download: https://www.divshare.com/download/[FILE ID]
Direct Download: https://www.divshare.com/direct/[FILE ID]
Full Image: https://www.divshare.com/image/[FILE ID]
Slideshow: https://www.divshare.com/slideshow/[FILE ID]

Images (mid-size and thumb may not exist for some files):

Full Size: https://www.divshare.com/img/[FILE ID]
Mid-Size (400px wide): https://www.divshare.com/img/midsize/[FILE ID]
Thumbnail: https://www.divshare.com/img/thumb/[FILE ID]

Video player:

Audio Player (set the height to 28 to hide the file description):

Slideshow Player (use the file ID of any image in the folder):

Document Viewer:

Uploading

Uploading to DivShare using the API is a two-step process. First, you call an API method that returns a unique upload ticket. Then you generate an HTML form, which sends data to the DivShare server and uses the upload ticket to identify the logged-in user.

Generating an Upload Ticket

An upload ticket is a unique code that is included in the form that you'll POST to DivShare's upload server — it allows us to identify the logged-in user without exposing sensitive information like the API session key or the user's password. Each upload ticket is specific to a certain API key, session key and user combination. It can only be used once, and it expires after 24 hours.

The PHP client will return an upload ticket when you run the following function:

$upload_ticket = $ds->get_upload_ticket();

Easy enough. If you're building another client, here's the XML response you can expect:

<?xml version="1.0" encoding="UTF-8"?>
<response status="1">
<upload_ticket>123-abcdefghijkl</upload_ticket>
</response>

Building the Upload Form

Now that you've got your ticket, you'll need to add it to your upload form. Check out this example, then we'll go through it piece by piece.

<form action="" method="post" enctype="multipart/form-data"><input type="hidden" name="upload_ticket" value="[UPLOAD TICKET]" />
<input type="hidden" name="response_url" value="[RESPONSE URL ON YOUR SITE]" /><input type="file" name="file1" />
<input type="text" name="file1_description" maxlength="255" />
<select name="folder_id">
<option value="[FOLDER ID 1]">[Folder Title 1]</option>
<option value="[FOLDER ID 2]">[Folder Title 2]</option>
</select><input type="text" name="email_to" maxlength="255" />
<input type="submit" value="Upload" /></form>

The Form Tag

As with any form that uploads a file, it must include enctype="multipart/form-data". Also note that the URL to upload to is https://upload.divshare.com/api/upload.

The Upload Ticket

Generate it as described above, and then insert it here.

The Response URL

Here's the important part. After our upload server processes your upload, it will redirect the user to this URL with a GET querystring of file IDs attached. For example, the response URL http://www.mysite.com/response_url.php would produce the following redirect:

http://www.mysite.com/response_url.php?file1=123456-abc&file2=123456-abc ...

The files will be named file1 through file5. If your response URL already has GET parameters attached, the upload server will append its new querystring with a & instead of a ?.

You can also use your response URL to handle custom fields from your upload form. Any field whose name is not specifically included in the example upload form above will be sent back to the response URL as part of the GET querystring. Since there is a browser-imposed maximum length for the resulting URL, you may run into some limits on this feature.

Files

You can upload up to five files at a time. Name each file file1 through file5, and name each description field file1_description through file5_description. A description value of "File Description (Optional)" will be ignored by the upload server.

Folder ID

Sending a folder ID, which must be an integer, will add the uploaded files to that folder. The folder must be owned by the logged-in user. You'll be able to easily populate this field with all the user's current folder titles and folder IDs upon the release of the get_folder_list method.

Send via E-mail

Users can enter up to 255 characters worth of e-mail addresses in this field, separated by commas. Spaces around the commas are acceptable as well. Each e-mail address will be verified by the sever to ensure it's in a plausible format.

Submission

This is just your standard submit button. Feel free to improve the feedback with some Javascript to show a progress image, or anything else you desire. At this time, the upload progress meter is not supported for API uploads, but we're working on options to include that in the future.

Handling the Upload Response

As described above, your response URL will receive a GET query with the IDs of the newly uploaded files. You can then run the get_files method to retrieve more info about each file, add the IDs to your own database for future use, or use them in any other way you please. From here on out, it's all up to you.

Logging out

At the end of your user's session, you can use the logout method to delete the current session key. This will return a logged_out XML element with the value of 1 on success.

$logout_result = $ds->logout();

Advanced API Development

Until now, we've demonstrated how to use the API with the existing PHP client, but we haven't really looked under the hood. This section will help you develop your own API client and know exactly what to expect from the server when it responds.

POSTing to the server

API POST URL: https://www.divshare.com/api/

Communication with the DivShare server happens via an HTTP POST — in the case of the PHP client, we use cURL functions to accomplish this. When you're putting together your own POST, here's what you'll need:

api_key — Your API key.

method — The method you're calling, such as login or get_files.

api_session_key — Required for all methods except login, which returns a new session key.

api_sig — A signature created by generating an md5 hash of your secret key, your session key and the parameters sent with your API call. Required for all methods except login.

Generating the API Signature

You'll need to generate a new signature to send with each call (except login, which doesn't require a signature). The ingredients are your secret key, your session key, and an alphabetical list of the other parameters you're sending whose names are not included in the following list: api_key, api_session_key, method and api_sig. Here's an example:

Your secret key is 123-secret.
Your session key is 456-session.
You are using the get_user_files method, and you're sending the parameters limit=5 and offset=10.

The string used to create your signature will be: 123-secret456-sessionlimit5offset10. Note that the parameters must be in alphabetical order, so limit always comes before offset. Each parameter should be paired with its value as shown. After you've successfully organized your data and created your string, you need to create an MD5 hash of the string. This is your API signature, which you should POST as api_sig.

On the server, we'll build our own signature using the same method — if they match, your API call will proceed.

XML Response Formats

So far we've shown a few sample XML responses, and we've created a PHP client that automatically parses the XML into a PHP array when it receives the data. To build your own client, you'll need more details on the possible responses for each method. Here's a list below, which we'll update to reflect any changes or additions as we continue development.

login

Returns the new API session key or an error. You don't need a session key or signature to call this method.

<?xml version="1.0" encoding="UTF-8"?>
<response status="1">
<api_session_key>123-abcdefghijkl</api_session_key>
</response>

get_user_info

Returns the user's e-mail address and first name.

<?xml version="1.0" encoding="UTF-8"?>
<response status="1">
<user_info>
<user_fname>Rob</user_fname>
<user_email>[email protected]</user_email>
</user_info>
</response>

get_user_files, get_folder_files and get_files

All these methods return file data in the same format. last_downloaded_at and uploaded_at are 10-digit UNIX timestamps. Folder title and folder ID will only have values if the file is in a folder. The will be an additional file node for each file returned.

<?xml version="1.0" encoding="UTF-8"?>
<response status="1">
<files>
<file>
<file_id>123456-abc</file_id>
<file_name>My Resume.doc</file_name>
<file_description>Resume (Draft 3)</file_description>
<file_size>0.4 MB</file_size>
<downloads>4</downloads>
<last_downloaded_at>1192417863</last_downloaded_at>
<uploaded_at>1192454938</uploaded_at>
<folder_title>Job Applications</folder_title>
<folder_id>12345</folder_id>
</file>
</files>
</response>

get_upload_ticket

As described above, this returns an upload ticket to use in the upload form.

<?xml version="1.0" encoding="UTF-8"?>
<response status="1">
<upload_ticket>123-abcdefghijkl</upload_ticket>
</response>

logout

This method deletes the current session key. It returns the following on success:

<?xml version="1.0" encoding="UTF-8"?>
<response status="1">
<logged_out>1</logged_out>
</response>

Errors

If your API call results in an error, the status attribute of the response tag will be 0 (zero). The error description will be returned in the following format, which may have one more more error nodes. We know this isn't a very robust error handling system, and we'll be improving it as development continues.

<?xml version="1.0" encoding="UTF-8"?>
<response status="0">
<error>Sorry, your e-mail and password do not match.</error>
</response>