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