New v2 API: What’s Not There Is Just As Important As What Is

This post is the first in a series from the product managers and engineers who built the new version of our API. They'll be discussing the design decisions and technical challenges that we faced along the way, so be sure to keep checking this blog every day for the next week. As Chris Yeh mentioned in his blog post, it’s been a pretty big year for the platform team here at Box. We’ve built amazing products and tools that enable our thriving ecosystem of developers, integration partners and customers to get the most value out of their Box experience. At the core of this experience is the Box API. This year, the team spent a considerable amount of time making our APIs simple and elegant, and today we are excited to make the Box v2 API generally available for everyone. Less is More The Box v2 API follows our passion for simplicity and elegance. We stripped out unnecessary fields. We simplified our payloads down to JSON only. We streamlined error messages to use HTTP standards so when something doesn’t work as you expect, you know why. We built an automated developer documentation system. We thought about how to make it easier to add new features next year with minimal disruption. We felt it was important to sweat the details and simplify as much as we could, because that ultimately translates into a more rewarding experience for developers. So, whether you’re thinking about building against our API or building your own API, you will appreciate that less is more. Building a Better API At the core of every business, there are key systems: CRM, ERP, billing, accounting, HR. At the core of every one of those systems is secure, reliable access to documents. Our customers are increasingly integrating those processes with Box. With this massive opportunity ahead of us, we made the investment to make our API 10x better. So, what have we been working on?

Symmetric Request/Response Model

Reuse of code is hard. We know that as well as anyone else. Wouldn’t it be nice if the Box API helped you reuse code as much as possible? That’s part of why we made our request JSON and our response JSON look identical. If you’re serializing and deserializing JSON to objects, then having one layer that can go both directions without conditional logic is elegant simple and easier to maintain. We like elegant - it makes things easier to document, and it makes it easier as a human to hold the concepts in your head.

Special Names for Dates and People

There’s magic in well-named things. There’s power in being consistent. We’ve made all the date fields in our JSON ISO-8601 dates. We name them all with _at. So when you see a field called created_at, you know it’s a date. Similarly created_by and modified_by use the _by to signify users, and you’ll see a consistent user-mini JSON format returned. The leading words can_ and is_ signify Booleans, so we’re expecting and will return a true or false in the JSON.

Why No XML?

I spent several years of my life implementing against the (completely insane) ACORD IIA standard. It took 2k of XML to tell the other system (an aging mainframe) that someone’s address had changed. What I learned the hard way was that XML as a format is horrendous at talking about objects. There’s an inherent impedance mismatch between XML and regular humans. JSON APIs, by contrast, are all about working with objects in ways that make sense to people. In order to use an XML API, you need to look at schemas and try to load into your head complex object-substitution rules and namespace definitions. Thankfully its use is falling by the wayside. The wave of pragmatic programmers that has swarmed from the consumer Internet to the enterprise Internet has helped usher out SOAP, WSDL, and WSI. Our polls showed less than 0.5% of our API users still wanting to use XML, so we simplified and got rid of it.

Files and Folder Include Breadcrumbs

When we first put out our v2 API beta, we didn’t include a folder hierarchy in the API. We quickly heard that many app developers were looking to display the breadcrumb trail in their app without having to store their own traversal path. We also found it useful when navigating from a shared link to be able to show the user their folder hierarchy. So we added a folders_collection to the API response.

Events – Push or Pull Notification

The v2 API includes the release of the /events endpoint, which actually was the work of two separate teams of engineers for over a year. The notion of a queued event stream is critical for transactional systems. Most of the banking world, for example, relies on MQ or JMS to deliver reliable messages between systems. We knew over a year ago that for Box to support transactional integrity for our biggest enterprise customers, we’d need to build out both the infrastructure to communicate about those transactions as well as an API to give that stream to our customers.

OAuth2 Box has always been rather pragmatic when it comes to authentication standards. To the astute observer, Box sat on the sidelines of OAuth, since we already had implemented a system nearly identical to it before OAuth became a standard. As OAuth2 was being written, we watched carefully. We watched Google and Facebook implemented their own flavors of OAuth2, and we debated the standard pretty actively internally. What grants were secure? What grants would our customers need to build out their integration solutions? We decided that the OAuth2 standard, implemented with a restricted set of grant types, is a good enterprise authentication standard. What we are releasing is a fairly small subset of the whole standard. We’re supporting what has canonically been described as the 3-legged auth process. We support bearer tokens as well as refresh tokens. Today in our launch we only support a single scope that is equivalent to our existing v1 auth scope. We are still actively debating other scopes, and you can plan on seeing several others released over the next few months. What Simplicity Enables Many of our partners and customers have already been building on the v2 API during our extended beta. We’re grateful for the many great examples they’ve shown us. Even more than that, though, we’re excited to see what the rest of our developer community will do with v2, so grab an API key and get started!