Original image © Paul Downey. Creative Commons License. Edited for use.

1 - Document first

Put away the IDE and pick up a pen. Good design starts at a higher level than the code, so starting by sketching out the different parts of your API as boxes. It will let you get a feel for where the boundaries are between different things. Once you can establish that, then you can get down into the business of deciding the language of your API.

Documenting first will help you to find the "right" way to layout your URIs, figure out what functionality you want to expose, think about how you want to communicate back to the users of you API and find annoying edge cases that may make you rethink your initial decisions.

I can also mean you can start developing your API sooner as you're sure what your doing is correct (or at least as correct as you can make it). It'll keep everyone on the same page as well, helping to avoid inconsistencies, leading to...


2 - Be consistent

Ask 10 developers what your URL structure should be/what your response should look like/how you should input variables and you'll get 10 different answers. The truth is, it doesn't really matter, as long as you're consistent about the implementation and don't make a real mess of things. Really great APIs are easy for developers to guess their way around, finding resources and features. Imagine:


 GET https://example.com/dog
 GET https://example.com/cat


If you want to see if there's a mongoose endpoint, the following is a good bet:


 GET https://example.com/mongoose


If the API isn't consistent however, the resource may be much harder to find:


 GET https://example.com/mongooses
 GET https://example.com/mongeese
 GET https://example.com/mammal/mongoose
 GET https://example.com/mammal?name=mongoose


It will also mean users of the API need to create edge case code and multiple different API endpoints to manage the poor design.


3 - Be immutable

There's nothing more frustrating for a developer using an API than finding out their application is broken because a change was made in the API overnight. Simply put, don't break your clients, because if you do, you become untrustworthy no matter how good your intentions were.

Once published, an API should not make any breaking changes. This can be really hard, especially when you, as the author of an API, finds out that there is a deficiency in the design. Unless you can guarantee that nothing will be adversely affected (and really, if you've published a public API that has any users, you can't make this guarantee) then don't fix it.

This doesn't mean you can't make any changes, just that the changes you make should not change the existing functionality. Fixing an API endpoint that's returning incorrect data is fine. Fixing an API endpoint where there's a spelling mistake in one of the returned fields is likely to break something for your users.

If there are enough problems and they are significant enough to warrant a change, then you'll want to have good change management in place. The best change management I've found, is to version your API. I know, I know, this is advice that many people disagree with, but I've never found an alternative that works as well, doesn't mess things up for your users and is clear that something has changed.


4 - Separation of concerns

In the case of API design, your data storage/retrieval should have no idea about the design of the API. If you split up a database table, your API should not need to change, just because you have a database table, you shouldn't have to write code to hide it away. Far too many API tools are tied to the data layer. This makes initial setup easy, but the time you save at the start of the project is not worth the problems you're going to cause yourself and your users when it comes to make some additions, fix bugs or change anything about your data layer.

There's a growing tenancy to allow ORMs to take charge in projects and use data objects to become way more important than they have any business being. There are a multitude of API generation libraries and plugins for different web frameworks, some of which are great...until they're not and you have to break part of your API out and away, leaving you with two different mechanisms for serving results. BaaS is starting to make exposure of your data storage more commonplace. If you're designing your own API, you want it to have longevity and you don't want unnecessary complications later, stay away from shortcut libraries and tools and make sure you design things yourself, from the ground up.


5 - Write for your audience (it's not always a computer)

Ok, so you've got your design drawn out, you're using HTTP methods like a bandit and you've got everything pinned down. It's time to really make sure your API is going to make other developers love you.

Sure, most of the traffic that's going to hit your API is going to be from computers, but computers don't care about niceties. It's also not computers writing the client code or trying to figure out what you API can do, that would be other humans. Make sure that you write you API to be read. It's just like any other code in that regard. Code will be read more than it is written, as will your API. If you make it make sense, be informative when something's gone wrong, and helpful when something may not be clear, you'll at least have an API that is easy to create applications for.


Bad implementation always trumps good ideas

19 September 2015 11:34 a.m.

Good practice in software development has always preached loose coupling and high cohesion.

While most developers understand this and try ...

Read More

New platform, new challenges

13 September 2015 19:13 p.m.

There was a question raised by a collegue of mine recently, that asked "How long should it take to get ...

Read More

SaltStack and Vagrant

14 February 2013 15:14 p.m.

Salt is an open source infrastructure management tool. While one use is to manage thousands of servers, it’s also very ...

Read More