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 ...

Read More


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