I have been responsible for the DeviantArt API for a while now and have learnt a lot about API design in the process, this post covers my top lessons from this project.

1. You Support Your Mistakes FOREVER!

This was a hard lesson learnt. As soon as you release anything, clients become reliant on your mistakes, and no matter how embarrassing you have to support them FOREVER (ish). It's not all bad though, committing to supporting your API even its bad points means clients/developers can trust your API, which is a big deal.

2. Get Versioning Right

Following on from supporting your mistakes, versioning is an important tool to help fix mistakes and grow your API over time. Implementation wise there are many ways to handle versioning. I would say there isn't a correct way, it just needs to be consistent.

3. Log All The Things

Having decent metrics helps spot errors in both server and client and you know pretty graphs.

4. Don't Write Docs Generate Them

Manually maintained docs for endpoints will become stale quickly. It's much better to generate docs from the endpoints themselves, then you don't have to worry about keeping them updated.

5. Support Reuse

In every system there are common elements, make sure your framework supports easy reuse of these in your request/responses. At DA we have the concept of macros that can be easily mixed into the endpoint config and handle efficient fetching etc.

6. Test Everything

Having a strong test suite is invaluable especially if you have any sort of SLA to meet. We have an extensive unit test suite for the framework and then an integration suite for all endpoints. We even create the integration test skeletons during endpoint creation so that devs cannot create endpoints without tests. All tests are ran on commit and we also use Runscope which runs a set of smoke tests every 15 minutes. All these tests mean we spot failures very quickly.

7. Dogfooding

One great way to improve your API is to use it yourself. For me that was working on the DeviantArt Android app . The main thing I learnt doing this was not to get overly fancy. API consumers generally just want the data, so your main job is working out how to provide that data efficiently. The other important one was considering how your return structures will be decoded, for example having a list of items where the item type is the key ['top': {...}, 'bottom': {...}] is a bad idea. This is because the consumer needs to parse both key and items to create that type, which in Java (strongly typed) etc is a pain when mapping to objects. Rule of thumb is to keep an items properties as properties of that item.

That's all, happy API'in!