Personal API Experience

Personal API Experience

Daily musings

Sharing my day to day lessons, ideas and contemplations of architecting, developing and maintaining services (API) in the global marketplace we call the internet.

Fireworks and APIs - “meh”

APIPosted by Craig Hughes Fri, January 04, 2019 14:34:58

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

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.


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

  • Comments(0)

Fill in only if you are not real

The following XHTML tags are allowed: <b>, <br/>, <em>, <i>, <strong>, <u>. CSS styles and Javascript are not permitted.