Every New
Year’s Eve we are wowed by extravagant fireworks from around the world – we anticipate
them and we expect them. This New Year’s Eve was no different, except for me – this
year I was in Copenhagen city center; on the balcony of a friend’s apartment, watching.

In Denmark
anyone, over a certain age, can purchase and set off fireworks during New Year’s
Eve. It’s quite spectacular – bangs, fizzes, pops and smoke for a number of
hours; explosions are constant and everywhere.

Some of the
fireworks are spectacular and clearly cost a small fortune, others are unexceptional,
but the result of all of them is the same. Firstly, there’s great expectation
followed by excitement in lighting the fuse. Then there’s anticipation; waiting
for them to go off, tailed by wonder as the explosion and accompanying light
show is released. In the end, there’s the “meh” moment – either because it was
the same as the previous one, not as good as the next one, or a little lack-luster
when compared to others.

Finally, it’s
all done. The show is over, the money spent and everyone goes home.

Since this
is a new year, and we generally try to aspire to greater things, let’s try with
our APIs. Let’s not simply build excitement and anticipation only to release an
API that’s “meh” and soon forgotten. Let’s try to do them right this time.


Before you
begin, make sure you understand your business. Make sure you understand how your
API will be used in the context of your business. Make sure your API will be
used to grow or enhance your business. And finally, make sure the purpose of your
API is clearly understood.


Work with
your colleagues, your business, your partners and your consumers. Understand
their needs, work through their ideas, grasp their constraints – work with the requirements.
Agree the contractual interface (payload, URLs, operations, etc.) and simulate
them (using SwaggerHub or similar). Let everyone play and plan ahead with the simulations
– there is no need for consumers to wait for the final product. Get feedback

Simple and reusable

Keep your
APIs simple and try make them useable by as many parties as possible (avoid single
consumer builds). Make them intuitive and keep them constrained to a single
functional responsibility. If you have to document your APIs too much, they are
probably too complicated. Mocking your APIs will help you understand if you’re
on the right path.

Loose Coupling

Don’t place
assumptions on consumers; don’t assume they understand the complexity of the system
behind your APIs – it’s not their responsibility. Your API interface should
abstract them from your complexity. After all, managing complexity is part of the service that
an API offers.


manage you APIs through their lifecycle. Give them an explicit version (using Symantec
versioning) and let your consumers know when new versions are available. Of
course, if you are already collaborating with your consumers, they should be
ready for your API changes.

So, fireworks
offer all the excitement, anticipation and wonder; followed by the “meh” moment.
Your API’s can offer the same, but try not to aspire to that – try to maintain
the feel-good excitement and wonder by delivering something lasting and worthwhile
to all.