Your API sucks : how to suck less

If you don’t want to be chased by a horde of angry developers with axes, here’s a few things to keep in mind. And also see the making less-bad API tips from my DDDScotland follow-up post.

User first : Design from the outside in

Use Test-first design. And get developers to test it. Preferably developers outside your team. Developers understand *Unit, so you don’t need Cucumber, but make sure you have the tests.

If there’s a standard, use it

Use standards. Use libraries that support those standards.If the standards aren’t enough, extend them in the supported ways.

Be consistent

Your API is not a tree. You may be able to track the history of your source code by counting the rings, but the external façade should be smooth and polished.

Be clear

Make it as simple as possible, but no simpler.

Be helpful, but only when asked

Have documentation handy, and don’t be afraid to link to other documentation, even from 3rd parties. But don’t require documentation for the happy path.

Advertisements

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s