Blog article
See all stories »

Fireworks or APIs - 'meh'

Fireworks

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

Understand

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.

Collaborate

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 on 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 to make them usable 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

Finally, manage your APIs through their lifecycle. Give them an explicit version (using semantic 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.

4615

Comments: (0)

Craig Hughes
Blog group founder

Craig Hughes

Chief Enterprise Architect API

Danske Bank

Member since

06 Sep 2018

Location

Copenhagen

Blog posts

17

Comments

3

More from Craig

Blog post
API

Chain of Trust

Blog post
API

API Misconceptions

Blog post
API

API: Arrays or named elements?

This post is from a series of posts in the group:

API

More generic posts and blogs relating with Application Programming Interfaces (APIs) including Open Banking and PSD2


See all