Humans are great at observational learning. As children we learn by observing the goals, actions and outcomes of others. Many programmers have applied this style of learning to improve their craft by studying and understanding code written by their peers. The same is true for our API design world. Reviewing and dissecting the web APIs that are available on the web can provide us with enormous insight into the design of APIs in general. In this post, we will look into the Box API and see what we can learn.
Box offers a cloud based storage service that allows users to store file based content in the cloud with the benefit of being able to easily share data with other Box users. The cloud storage market is crowded and highly competitive, but based on their marketing, Box is trying to differentiate their product by focusing on enterprise customers.
Easy integration with devices and applications is a critical feature for cloud based storage products and a web API is the key to facilitating this type of connectivity. A well designed API is likely to increase adoption of Box’s service, and more importantly, a badly designed API is likely to drive potential customers away from Box and towards their competitors.
Given that the API is all-important for this domain, let’s take a look at what the team at Box has put together.
Number of mouse clicks required to register: 11
Approximate time to complete registration: 4 minutes
Registering a new developer account at Box is relatively straightforward and painless. I really liked that I only needed to provide an email address, phone number and name for my app in order to get started with the API.
I was required to create a regular Box user account before I could register as a developer which is fairly standard for APIs built on top of user based services. I did find this part of the process a little bit confusing as I was dumped into the standard Box registration with no guidance or links back to the developer portal when my registration was complete. But, this was a very minor quibble as the majority of new Box API developers may already be existing Box users. Overall, I’d categorize the registration process as quite good.
Aside from the actual registration, I would have loved the ability to play with the API anonymously in some form in order to evaluate the API before making a commitment to the site. In an ideal world, I would only have to register when Box really needs to know who I am and what my proposed application will do. In other words, I’d have liked to gracefully transition from being an interested visitor to a fully-fledged application developer for the API. In web design circles this as known as lazy registration and it’s something I’d love to see more of in the API world.
Clarity: Very Clear
Level of Depth: Medium
The Box developer portal provides a main documentation page as well as a few task specific guides to help you get started, authenticate apps and work with Box files. These mini-manuals are really effective in reducing the learning curve for developers who want to dive right in and the Box guides certainly gave me immediate insight into the use of their API.
The box API developer home page
In terms of visual style, the documentation site is clean, attractive and easy to read. It’s esthetically pleasing, has a minimalist style and uses a navigation structure that makes it easy to find content in a non-linear fashion (which is how many developers read API documentation). I also really liked the way examples were provided along – sside the documentation of resources – this made it very easy to glance back and forth between the description of an activity and the demonstrated example.
As usable as the documentation portal was, there were times where I found it difficult to find detailed information. For example, I experienced some initial moments of frustration when I was unable to retrieve the list of folders in my root directory. Intuitively I tried:
But, I received an error message in response. It turns out that the correct way to retrieve the contents of the root directory is:
In fairness, this URI pattern is actually well suited to the task and the information is documented within the Getting Started guide as well as the Get Information About a Folder section. But, well documented examples for these types of basic tasks would make the API easier to learn.
The Box developer blog acts as an additional form of documentation and there is a lot of useful information on the background for API design decisions, additional details on using the interface and announcements of planned changes. As developers increase their usage and comfort with an API they usually seek out this type of contextual detail, so it’s definitely worthwhile to provide it.
Word Count: 3,020
Allow me unequivocally state: I Am Not a Lawyer. If you are planning on embarking on any serious business ventures using this API, please read the ToS yourself or better yet, engage the services of someone who doesn’t start out by telling you how unqualified they are.
Nevertheless, I did it take it upon myself to peruse the terms of service for the Box API and weed out any potential gotchas that a legal neophyte might find. Beyond the standard clauses for indemnification and liability that I’d expect to see in any software product, the section titled Application Requirements and Restrictions section caught my eye. Here are a few of the items that might impact potential developers:
All in all, I don’t find these terms to be overly restrictive, but it is definitely worth a read and some extra consideration if you are serious about using this API.
Architectural Style: HTTP-CRUD
Message Formats Supported: JSON
According to the documentation, Box describes its API as “striving to be RESTFul”. REST has become a contentious term in our industry, so as a service to the REST purists in the audience, I’ll put this API through the ringer and give it 3.5 Roy Fieldings out of a possible 5:
3.5 Roys means that you will not find the full embodiment of REST here.
But, the ability to adhere to an academic’s PhD dissertation shouldn’t be the core focus for a commercial product. Instead, a good web API should be designed in a manner that meets the needs of its intended audience, so let’s dig in and take an objective look at the interface itself.
The Box API provides an object based HTTP (or HTTP-CRUD) based API that supports the JSON message format. For clarity, I’m talking about the very familiar interface style in which a set of resources or nouns are identified for a client application to access using standard HTTP methods like GET, POST, PUT and DELETE.
The use of HTTP-CRUD isn’t a big surprise, but I was taken aback by the lack of XML support considering that Box is targeting enterprise customers. But, according to their blog, the usage of XML was insignificant in the previous version of their API. This is a rock solid reason to make a design change and is a great example to API designers of making decisions based on the actual needs and desires of their target audience rather than speculation of their behaviour. I suppose it may also be a sign that the march from triangle-brackets to curly-braces in API messages is inevitable.
As you would expect for a file storage service, the Box API identifies files, folders and users as resources. At their heart, files and folders are collections of items and Box provides the pagination and field projection features that have become must-haves for collection based responses.
For those unfamiliar with these concepts, pagination is a way of breaking large collections of data into smaller chucks and the Box API uses offset and limit query parameters to allow developers to select virtual pages of data. If you are looking for a basic and clear example of how to do pagination for an HTTP object interface you need look no further than this interface.
While pagination allows developers to control the number of items they receive, field projection (or field selection) allows a developer to choose the level of detail for items within a collection. This is particularly important for objects that have a large quantity of properties and is used effectively in the Box API with minimal responses provided by default for collections.
In addition to read operations, a set of write activities are included for application developers to build apps that can store content in the cloud. Files can be uploaded using a multipart form post (the method used by HTML’s FORM element) and folders and file resources can be created or updated using POST and PUT methods. The use of HTTP’s PUT for partial updates may not sit well with those who are looking for full adherence to the HTTP specification, but practically speaking I don’t think it negatively impacts the usability of the API.
Outside of this somewhat discretionary design point, the team at Box does a great job of adhering to and implementing standards. The use of standards like ISO 8601 for dates, HTTP header fields for conditional operations and meaningful HTTP error codes help reduce the learning curve for developers who are used to developing on the web.
Overall, I enjoyed using the Box API, but having worked with interfaces that provide hypermedia features the lack of hypermedia links felt conspicuously absent. I particularly missed them in the responses that contained collections; embedding links to atomic items is so much easier to use than constructing URLs based on IDs.
Communication Channels : Stack Overflow, Github, forum, blog, Twitter, email
The Box team does an outstanding job of communicating and supporting their developer base. They have all of the important community channels covered, but more importantly they are actively engaged in the community that they have started There are some API publishers who tick the social networking boxes at launch time but aren’t present to actually answer questions about their API after a few months. This isn’t one of those organizations – it looks like these guys really get it.
Box API Questions at Stack Overflow
In terms of troubleshooting and debugging, the error messages received from the Box backend are fairly terse with only a link to a generic error documentation page provided. Additional guidance and metadata in error messages would have been nice and might have helped me when I was trying to figure out how to retrieve a list of files from the root directory.
Protocols Supported: SSL, OAuth2
Any organization selling to the enterprise market needs to take security seriously and Box certainly appears to do that. They’ve incorporated OAuth 2 as an access control mechanism, SSL as a mandatory protocol and the Box service itself boasts additional security features for privacy and availability of files.
But, the challenge I faced almost immediately with this API was that I needed OAuth 2 authentication credentials in order to make any API calls. I’m not against securing access, but protecting all API resources in all circumstances means that I can’t try anything until I build and deploy an OAuth 2 client that can:
That’s a lot of work for me to do in order to make my first call. If I was shopping around, I might consider using a service that lets me get started right away, especially if I’m quickly hacking together an app that needs a cloud storage integration immediately.
Pricing Mechanism: N/A (free for public use)
The Box API is free to use for developers who build publicly available applications. I saw no evidence of tier based pricing and the rate limit appears to be applied globally to all developers. There may be an undocumented cost for developers building private or intranet applications (as described in the Box API terms of service).
The Box team have invested a lot of time and money into its API solution and it shows. Overall, this is a great API and it left me with the impression that the designers really put themselves in their user’s shoes in order to build a solution that would feel familiar, safe and simple to use.
It’s impossible to judge another designer’s API without understanding the business objectives and technical constraints that make their situation unique. However, we can learn a lot about the art of API design by observing and discussing the APIs that are in the wild. The Box API provides us with a great example of an effective HTTP-CRUD style API and a documentation portal that is demonstrably easy to use.