Introducing the V2 API

Why a V2 API?

At Box, we're focused on making it possible for customers and partners to more quickly and seamlessly integrate Box's functionality into their own applications.  Part of that is taking stock of what's happening outside of Box and how it affects our users.  More people every day use their own phones and tablets, alongside with their company laptop to accomplish their work assignments.  They've grown accustomed to intuitive interfaces, and are increasingly demanding that enterprise applications leverage some of the interaction models and tools they see in their lives outside of work.  We're also seeing an emerging democratization of the app-development world.  SXSW talks like “Program or be Programmed” and programs like Codeacademy are making people more comfortable with putting together their own small programs.

In light of these trends, Box’s platform team spent several months evaluating when, how, and how often our APIs are used.  We looked at what was missing from the existing API, and how we could re-structure it to be better.  Part of Box’s DNA is to exceed the expectations of our users, and we decided that our existing API had done that job initially, but that we needed to take it to a new level.

We wanted our API to be better across many dimensions:

  • Easier to get started for first-time developers
  • Easier to comprehend the concepts
  • More customizable to the needs of power-API users
  • Fewer unused or hidden features

We decided that our API needed more than just a tune-up.  They needed a fresh start.  Our API suffered from a fairly common problem faced by other 5+ year old platforms: we had expanded its surface area over many years, and had been inconsistent about what we named things, how we returned objects, and what the expected default behavior was. We were also simply behind, both technology and technique wise, for what is considered a state-of-the-art and elegant API.  So we decided to change that.  Our research led us to build a pragmagtic RESTful API.   We focused on an elegant set of nouns that intuitively capture the functionality, and provide elegance in their simplicity.

Making Simple things Simple

I’m often asked “Why do you care about elegance for an API?  Only programmers see it.”  But with the revolution in programming that's going on, more users are programmers.  So while most programmers have previously been expected to be geniuses that can figure out arbitrarily complicated things, the new target audience is everyone.  So we decided to make all the simple parts of the API simple, and open it up to anyone that wants to do any amount of programming.  Programmers are human beings, and making an API easy to interact with is akin to making a smart phone intuitive to use.  So Box’s platform team decided to apply the kind of design discipline, diligence and attention to detail that is normally reserved for consumer electronics.

That focus on design elegance gives everyone an order of magnitude less friction to getting started, or using the V2 API.  That lower friction in learning means less time fighting with code, and more time to unleash your creativity.  For our customers and partners building enterprise applications or integrating their existing enterprise apps to Box, it means that ‘aha!’ moment comes sooner.  It means they're up and running with the Box API more quickly.  It means that not just expert programmers, but anyone with a motivation to learn—like those who make it through Codeacademy courses—will be able to use the Box API.

The Evolving Design Ethos

Just as you’d look at a car from 1990 as being old in it's style, programming design ethos changes, albeit in a web timeframe.  As little as 3-5 years ago, state-of-the-art was to design APIs in terms of actions that you wanted to perform.  Box’s V1 APIs were named things like  “upload_item”, “get_file_info.”, and “delete”.  While these were nice descriptive names that helped programmers know what the API is going to do, they tended to get slightly different names across different objects.  So, over the years, we ended up with “delete” for folders and files and “delete_comment” for removing a comment.  Multiply that across 50-75 different actions that you want to take, and it can become hard to have a mental model for how you'd remove a tag, or perform any other number of things you would assume our API would let you do.

Today’s programming ethos, in contrast, has learned from that explosion of information.  Organization of a state-of-the art RESTful API is noun-first. Instead of verb-then-noun naming, we've moved to noun naming, with various verb options.   This makes a lot of sense because the number of verbs don't change very much across the API, and HTML already gives you those verbs.  It also works really well with all the existing tooling.  Probably 90% of editors will automatically group alphabetically.  Noun-first naming groups all the operations for a single noun together visually.

Clearer Documentation

Just as the state of the art for the API naming has evolved, so has the available documentation.  Box knows that for our API to be easy to use, we have to deliver great documentation.  And this is a case where imitation is the best form of flattery.  We studied the documentation for many web apps APIs, and realized the bar had been raised by a lot since our V1 API was published.  So we felt very strongly that the same design ethos we applied to the V2 API, was worth applying to the documentation as well.  And you can see it here.   You’ll see every noun-verb combination endpoint with examples, and clearly laid-out parameter lists and options.  Ultimately the test of the API design elegance is a bit ironic.  The better our documentation is, the less of your time you'll spend reading documentation.  Once you’ve learned how to call one API, you’ll be able to grok the structure, and not have to rely on documentation for getting simple things done.

Get Started on V2

So let’s say you are interested in building your own little app.  It could be an iPhone app, or a website, or even just a command line script you want to run on your laptop to automate your backups.

Each Box API noun has a very limited set of verbs you can use against it.  For most nouns, it starts with being able to create, retrieve, update or delete them.  That’s a metaphor that many people know as CRUD.  In order to keep things simple, we aren’t inventing new ways of thinking when they aren’t needed.  REST is built on the simple philosophy that you can organize your nouns, have a very simple set of verbs that act against those nouns, and you can accomplish most behaviors you want to with that simple system.  Box’s new API does just that.

For example if you want to rename a file on Box, after you authenticate, you’d send an http PUT request to the URL, and include the JSON body with the new name for the file with the ID 1234.   Every object in Box has an ID, and you can address it directly by putting that ID into the URL you call for the API.

Of course there may be some extra verbs that we need to introduce, but we keep their invocation predictable and simple.   Copying a file is simply an http POST request to with a JSON file payload that includes the name for the new copy of the file with ID 1234. The call will return a JSON file payload that includes the ID of the new file, as well as all the other information about the file you’d expect, like when it was created, whom by, and where it resides in your folder structure.

Structured responses

Let’s take a look at the structure of one of the API responses.  For a call like this:


You obtain:

    "path":"\/Sheet Music\/[
        "name":"Sheet Music"

You get this nicely structured JSON response, that includes not only information about the file, such as it’s sha1, create and modify datestamps, and link info, but also information about several people associated with the file.

Based on the HTTP verb you call, you can either retrieve (GET) the information about the file, modify it (PUT), or delete it (DELETE).  All three verbs work at the same simple URL.  We’ve also made sure that the URLs for objects follow their object type.   For files you call a ../files URL,  for folders, it's a ../folders URL.   As you might guess, to get more information about one of the users you’d call the ../users endpoint.

Go to it

So that bring us to today. We’re launching the first set of V2 API endpoints, including /files, /folders, /comments, /discussions and /events.  We’re also launching our brand new V2 API documentation, which I encourage you to look at, and ask us questions about if something isn't obvious and simple.  And even if it is, I'd love to hear what you think about what we've done.

Tags: api, json, restful, sticky