If you read my previous blog post on competing in the API economy, you probably have a feel for just how important APIs are for modern organisations. Implementing an API strategy unlocks internal assets and makes you a competitive and relevant force in our diverse and fast-changing tech landscape.
When planning your API strategy, your goal should be to reach internal API maturity (see my previous blog) and eventually create internal or external business value out of your APIs, monetise them. 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 start 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 its completion are going to be slow and expensive. Not only the API definition and implementation need to be modified, but also the deployment should be redone again.
As you can imagine, this approach doesn't fit into modern requirements, where assets need to be unlocked and available for consumption very quickly.
Bad practice #2: Bottom-up approach
Unfortunately, the Bottom-up is a very widely-used approach. Developers design and implement APIs solely based on their knowledge of the backend systems to be accessed by APIs. There's no feedback from consumers (e.g. UI Developers) until the API implementation is completed. What does this mean? Such APIs become the "decorative wrapping" for the backend functionality. APIs created without consideration of user experience (UX) are challenging to use. They tend to retrieve too much redundant information from the systems and have big payloads leading to a more significant overhead on the network. Eventually, consumers stop using them. The lesson learnt here - APIs must match UX and user journeys if you want them to be successful.
Bad practice #3: Don’t design it, just build it
Rushing into the development and skipping the design phase altogether is the worst approach! The process is not accompanied by any documentation, and the APIs are implemented on the fly during the sprints.
The danger of the approach is that it leads to the proliferation of APIs, which very few people know where to find and how to use. It creates a tight dependency on the individuals who created these 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 is correct. But what is the right approach then? The answer is - design first! We can roughly divide the process into 2 main stages - the API definition design and the actual API development.
The fundamental principle here is that feedback is given early in the cycle, which saves you both time and money. Using the modern API design platforms or doing this manually, developers design and document APIs, and create mock endpoints (returning sample payloads). The APIs consumers can use these endpoints to test user experience, payloads, return status codes, resources definitions, URIs, etc. At this point, the API is just a shell without any implementation or the backend logic. You only define the "contract" to facilitate the testing process, make it rapid and straightforward.
After several iterations of the above process, the consumer is happy with the results and eventually signs off your API. From then on, the API definition is solid and stable, and it's unlikely that you'll require to introduce any more changes. If you do, they'll be minimal.
The first phase is over, and everyone agrees on the API "contract" (i.e. the API definition). Now 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, these activities can be executed in parallel.
Thanks to the quicker design phase and the service and client development running in parallel, the go-to-market time is reduced dramatically.
In a proper agile setup, the service builds are continuously verified against the approved API definition. The service developers know when they are "breaching the contract" because they'll detect non-compliance right away.
The API Design First approach is the only way to go! All leading vendors support and promote 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!
Read more about our API-led integration framework and how we approach the API design and development.
