Tuesday, October 4th, 2011

The Absolute Beginner’s Guide to the Box APIs

By

For anyone who’s ever thought about hooking up their application to Box for Cloud file storage for their users, be it your own homegrown iPad app, or a portal on the company intranet, the Box APIs are your ticket to getting all the features and functionality that you’ve come to expect from the Box UI. Want your users to share a document? There’s an API for that. Want your users to see who’s collaborating on their folders? There’s an API for that. Want to see all the comments from the collaborators? There’s an API for that too. Basically anything you’re already doing with your documents on Box, you can do via an API. So fire up your Ruby/php/Python/Java application, and mix in some Box goodness. Your users will thank you for it!

To get started, go to http://developers.box.net and check everything out. Here you’ll find the developer documentation, links to the Developers Blog, the developers Forum and information about the various API calls you can make. There’s a wealth of information for you to explore, so feel free to poke around for a bit before moving on.

Now that you’re acclimated, you probably want to build something badass…but how do you do it?

The first thing you’ll need is a Developer’s key from the Project Setup Page, so head there to create and name your own application. My first one was called “PeterTest,” (creative, right?), but yours can be anything you want – even “Unicorn Rainbow Power” or “Best App Ever.” Next, copy the API key we generate for you. We know you’re excited, but don’t go sharing the key with other people, as it will grant them access to your Box application. To be brief: Keep your API key secret! However, you may want to write it down (or copy and paste it into a text file somewhere handy), as you’ll need it for the next few steps.

It’s helpful to walk through the basic API call stack in a browser window, so just click the Get Ticket API Function page and scroll down to the REST Request. Copy and paste the https://www.box.net/api/… line into a browser bar, and replace the stuff after the equals sign with the top-secret API key you’ve written down. After that, load the page on your browser to get a response that contains your very own authentication ticket. Depending on your browser, you may need to view source to see the XML that comes back. This is another thing to keep semi-secret! This one isn’t quite as critical, since you can generate as many of these as you want. Again, I recommend that you cut and paste the ticket part of the response into your text file; I put mine on a separate line from my app_key.

Great. Now you can move to the next step and use that ticket and app_key to get an auth token. Go through the same basic steps:

  1. Navigate to the API function you want to try (get_auth_token)
  2. Copy and paste the https:// part out of the REST Request example
  3. Edit the request to put your own api_key, ticket, and any additional parameters you want to try
  4. Hit return and fetch the response

Once you have an auth_token, you can call any of the other APIs you want, and the pattern to do it is the same. I suggest you try the get_account_tree with the params[onelevel] set after you’ve uploaded a few files into your Box account. Also good is get_comments, get_collaborators, as well as get_file_info.

You should now have a pretty good idea of how to write your own programs against the Box APIs. There are also starter libraries available to hit these apis on github. If you have any lingering questions or comments, feel free to reach out to the dev team on twitter @BoxPlatform or in our developer forum. Good luck!