British software developer and international public speaker on software development, Martin Fowler, once famously said, “Any fool can write code that a computer can understand. Good programmers write code that humans can understand.” His book ‘Refactoring’ has been a best seller for decades and is a guide on how to transform code safely and rapidly, helping developers build better code. Exactly these same principles should apply when looking to develop an API-first approach to software engineering.
But first, what do we mean by an API-first approach? This is a software development method that prioritizes the design of APIs before writing any other code instead of treating them as an afterthought. It is different from the traditional approach, where the application code is written first and the API is added later.
This approach lets teams construct applications with internal and external services delivered through APIs. It is a strategic approach that centers on the API, treating them as first-class products. It is designed, implemented, distributed and maintained by developers for the developer community so that API customers (developers) can build better software applications, services or wider IT systems by simply and easily ‘calling’ those APIs.
A Shift in Mindset
As mentioned, to achieve this the API must be created as a first-class product. In other words, it is not the backend for an application, it is a product in its own right. But more importantly, it is a product for developers to share with other developers. However, approaching APIs in this way requires a shift in mindset.
To understand that shift in mindset, let’s look at how not to approach API-first engineering.
When we undertake an API project, we typically design our API specification and build code around it, then upload the API definition into a repository or internal documentation to host the API definition. In parallel, to start serving traffic, the same API definition will be duplicated into the API management runtime. We often think this is how you go about API-first engineering.
Don’t get me wrong, this is a good starting point, but when you have an internal API definition (and today, 70 to 80% of the APIs built are internal APIs) stored away from the runtime, over time, your API definition will become outdated from the actual runtime. You might, for example, introduce a core parameter that you do not have in your API definition, which means whoever goes to use the API suddenly finds it hard to use.
In a small organization where developers sit closely together and interact with each other, this might simply be a question of talking to each other to easily sort this out. However, this is much harder to do in a larger firm with multiple offices and locations. Here, in plain truth, you are not doing API-first engineering correctly, because you should not need to ask a clarifying question if you treat the API as a product. The user manual will provide all the information you need.
Viewing APIs as a Product
Designing your API as if it were a product means thinking about it in the same way as you would a physical product. Therefore, how can you improve the product’s market fit? Does it offer enough functionality for users? What about future users? Does it provide adequate messaging, and so on?
You must also treat it as a primary user interface. Your API is the interface for your underlying data or functionality system; therefore, you must also create it as a first-class user interface.
Maintainability is also important from the provider’s perspective. How can you patch your API without affecting your consumers? What about the debuggability of the API? Can you practically work out what the errors are and treat those that need debugging? Can you also send the payload outlining exactly what your users should expect or what has gone wrong, so users can easily fix this themselves and save time?
Maintaining API Consistency
Next, you need to think about how you implement and adhere to a foundational design and maintain API consistency. Your API should be implemented independently, as in the underlying technology should not drive your API. But you must build a holistic API architecture and design — APIs that provide a mix of basic functionality, domain APIs and experience APIs, which provide digital experiences to your consumers. This means you need to implement an independent holistic API-centric architecture that is domain-driven in design with cell-based architecture for reusability. Your API design should reuse organizational domain models and should be able to fit into organizations’ API architectures. In other words, when you are designing your API, you need to make it generic enough to think about all the ways it could be consumed and adhere to existing domain models.
Descriptive Documentation
The importance of composing explanatory and reliable documentation with descriptive API specification standards and patterns is critical. You will have different documents for different purposes, and you need to make sure your documentation is straightforward with reliable purpose-driven documents, guides and solutions. Well-planned and composed documents will help your consumers to easily adapt to your product — the API.
Discoverability and Ease of Use
The importance of improving the discoverability of your APIs should not be underestimated. Your consumers must find your product — whatever platform or marketplace you are using — you should be able to easily find your APIs; so, make them searchable with metadata and tags. We often tend to overlook the importance of adding API metadata, but API metadata immensely helps to improve the discoverability of the API.
Finally, how easily can your APIs be used once your consumers find them? Ease of use should be seamless, without any friction. Design it as if you are designing the quick-start guide of a product.
API-First Engineering Strategy Enhances DevEx
An API-first engineering strategy aims to enhance developer experience and productivity by providing an API marketplace with improved discoverability, enabling developers to quickly find the resources they need. Once discovered, with the help of improved consistency, documentation and ease of use, developers will be able to use APIs in their new applications and systems. It should enhance API security and deliver better compliance and governance, ultimately enabling developers to write code that humans can understand! Simply put, using APIs should be faster, save costs and provide better digital experiences.
Good luck defining and implementing your API-first engineering strategy.
