,

API Series: Guiding Tenets of the API

When we first started design discussions for version 2.0 of the Znode API, we talked about all kinds of things. What should the URLs look like? What technology should we use to build it? Should we support both JSON and XML or just one or the other? If based on REST, how far do we take it? How do we make the endpoints flexible enough to support robust querying and filtering? We asked ourselves all kinds of questions, and in doing so we came up with a few tenets that guided our approach to the overall design and implementation of the API.

Tenet #1: Easy to Consume

Our primary driving tenet with the API is that, above all else, it must be easy to consume. To put this in perspective, think about two other well-known APIs: PayPal and Stripe. PayPal’s API is historically bad and hard to use due to poor documentation and inconsistent design. Stripe is at the other end of the spectrum and has a really nice API with good documentation, sample data, and a design that is consistent from one call to the next.

We wanted our API to be on the side of the spectrum that Stripe is on, and in fact, we used Stripe’s API as part of our design inspiration. And we think we’ve succeeded. All of our endpoints are completely consistent across the board, and we provide thorough documentation and sample data at every step along the way. We took the guesswork out of using our API, and all of this together makes for an API that is easy to understand and use.

Tenet #2: Predictable

The second tenet of our API design was that it must be predictable in nature, and this is a direct correlation to a consistent design. Specifically, this means that the behavior exhibited for every endpoint should be the same.

For example, every time you make a successful GET request to retrieve data, you will not only receive the expected data, but you are also ensured to get back an HTTP status code of 200. Similarly, when you POST data to an endpoint to create a resource (such as adding a new product), if successful you will not only receive back the newly created resource, but also a 201 status code and a location header with the URL for where the newly created resource exists.

Predictability is an important aspect in any API, and the Znode API has it in spades.

Tenet #3: Discoverable

Another tenet of our API is that every aspect should be discoverable, and in the Znode API this comes down to two things: 1) the built-in help docs and 2) being able to open endpoints in the browser. Let’s start with our API documentation.

The Znode API help is built directly into the API itself. There is no Word document or PDF that you have to read through to know how to use the API. The API is a living, breathing thing that you can understand as you use the various endpoints. The homepage of the API lays out all of the parts that make up the API and what they mean, while each endpoint help page lists all of its supported features and sample data to get you up to speed quickly (which also serve as the perfect reference material).

Being able to open endpoints in the browser was also important because it allows you to “see” and “touch” the API with your own eyes. You can easily open any endpoint URL in a browser and play around with its options – expands, filters, sorting, paging – and see the data that gets returned. This goes a long way toward providing consumers of the API a high comfort level.

Tenet #4: Wide Open

Finally, the last tenet of the API is that it needed to be completely open. In other words, we didn’t want to hide any data. The reason for this is because the API serves two purposes: it’s used to build frontends for applications and it’s used for integrating with other back office systems.

We also understand that we don’t know exactly how every customer will use the API and the underlying platform. Every customer’s business is different and it would be ill-advised of us to try and determine how the API should be used. It was created to provide the biggest extension point of the Multifront platform, and that couldn’t happen if we limited it in some ways. So we left it wide open and we’re excited to see what people build with it.