How to design the perfect API (API series, part 2)

Dec 13, 2018 Written by Matteo Formica | Head of Integration Technologies

If you read my previous blog post on competing in the API economy, you probably have a feel for just how important APIs are in modern organisations. Implementing an API strategy will unlock internal assets and make you a competitive and relevant force to be reckoned with in our diverse and fast-changing tech landscape.

Your goal will be to reach internal API maturity, and eventually create internal or external business value out of your APIs. You'll be most successful, saving both time and money, if you approach your API design in the right way.

To give you an idea of what that means, I will start off by breaking down the most common API design faux pas.

So, how should you not build an API?


Bad practice #1: Waterfall approach

This approach designs, builds, packages and deploys the API (as a linear sequence of activities) and then finally tests it.

There's no iteration in the design phase here, and the whole beginning-to-end process is long and slow. Since the API isn't released for testing until the very end, there's no chance for feedback until the whole process is finished. Any changes to the API you make after this are going to be slow and also expensive, because both the API definition and implementation need to be modified, and deployment will need to take place again. It's only when all this is done that you can test your changes..

Bad practice #1: Waterfall approach

As you can imagine, this approach doesn't fit into modern requirements, where assets needs to be unlocked and available for consumption very quickly.


Bad practice #2: Bottom-up approach

Bottomup approach

This is a very common mistake, which happens when developers design and implement APIs solely based on their knowledge of the backend systems that the APIs are supposed to access. In this approach, there's no feedback from consumers (e.g. UI Developers) until the API implementation is done. What does this mean? The APIs that are created this way don’t reflect any user experience (UX) at all; instead, they are “wrapping” the backend functionality. This means that these APIs are difficult to use, return a lot of redundant information and big payloads (this can also mean a bigger overhead on the network). Eventually consumers will stop using them, and you've got a big waste of time and money on your hands. The lesson learnt here is that APIs need to match UX and user journeys, if you want them to to be successful.


Bad practice #3: Don’t design it, just build it

This is probably the worst practice of them all... It's where the design phase is skipped altogether, so no documentation is written anywhere, and the APIs are implemented on the fly during the sprints.

API design: Don’t design it, just build it

This leads to proliferation of APIs, which very few people know how to find and use, and creates a dependency on the individuals who wrote the APIs. I could go on and on about why you shouldn't use this approach - the reasons are endless!


The right approach

If you look at the pros and cons (well, just cons really) of all the approaches above, it's pretty clear that none of them is the right one. But what is the right approach then? The answer is design first!

API design: the right approach

The key principle here is that feedback is provided early in the cycle, which saves you both time and money. Whether you're using the modern API design platforms or doing this manually, developers will design and document APIs and create mock endpoints (returning sample payloads), which the consumers can use to test user experience, payloads, return status codes, resources definitions, URIs, etc. At this point the API has no implementation, and no backend logic has been implemented either; it's only the “contract” that's being defined, so the process is very quick.

After a number of iterations of the process I described above, the consumers will eventually sign off the API definition. From then on, the API definition is quite solid and stable, and it's unlikely that you'll need to make any more changes - if you do, they'll be minimal.

When this phase is over, and everyone agrees on the “contract” (i.e. the API definition), both service development (the actual API backend, which can be an integration with an existing system or with a microservice deployed somewhere) and the consumer app development can start. As long as the API definition doesn't change, they can proceed in parallel.

You can appreciate how the go-to-market time is dramatically reduced, thanks to the quicker design phase, and thanks to the service and client development being parallelised.

In a proper Agile setup, the service builds are continuously verified against the API definitions; that means the service developers will know when they are “breaching” the contract, because they'll detect non-compliance right away.

API Design First really is the way to go - all the main vendors are promoting it in their tools and platforms, including MuleSoft API Designer, Google Apigee Edge, AWS API Gateway, WSO2 API Manager and Dell Boomi.

Consider what I've advised in this blog post, and good luck on your API designing journey!

We’d love to hear your opinion on this post