When APIs Go Wrong: Forgetting the “I” Stands for “Interface” Not “Implementation”

DZone 's Guide to

When APIs Go Wrong: Forgetting the “I” Stands for “Interface” Not “Implementation”

Managing your API contracts as first-class products unlocks the full potential of your interfaces without having to bond them to the implementation details

· Microservices Zone ·
Free Resource

After some years working around enterprise software and focusing on APIs and event-driven architecture, I have found that there are still common misconceptions around Application Programming Interfaces or APIs. They come in different flavors and versions and go from very simple misunderstandings to soon-to-be disasters. One of the most important ones I come across frequently, is the neglect of managing API contracts as first class products. 

For a long time, I have heard customers and developers talking about applications and services as “APIs”. Hence, forgetting that the “I” in APIs stand for “Interface” and not for “Implementation” binding together the underlying implementation with the contract used to abstract such implementations. Making this kind of bonding between the contract and the implementation details limit the benefits of having an API and the supported tools and practices to manage its lifecycle. This kind of rationale is common when the “code-first” approach is the only one used to build services and applications.

In consequence, the importance of having a “contract-first” path for building APIs like the ones used to connect services in modern day architectures becomes more relevant. Similar to other development techniques like Test Driven Development (TDD), using “contract-first” allows you to think upfront about the desired outcome of your API. In the case of RESTful APIs, using documents based on specifications like the OpenAPI to describe the interfaces as the “contracts” enable your APIs to be managed as standalone products. 

The control and governance of this contract based APIs as a Product (APIaaP) has led to the rise of API Management as a tool now ubiquitous in modern application development.  API Management helps with the administration of the lifecycle of the interfaces, versioning and linking with the actual available implementations. In fact, such lifecycles can differ from the ones of the implementations. This kind of decoupling brings the benefit of minimizing the impact in the API consumers when a new implementation is deployed. 

As it was stated before, when we merge the interface and the implementation of our services, we limit the potential offered by using APIs. In the case of RESTful APIs, the interface is the contract described in the OpenAPI document, while your service would be the java  implementation for that interface. In other words, the API is the OpenAPI document not the java code you are deploying in a container. 

Having a “contract-first” approach to APIs allows you to leverage the full benefits of decoupling the service from its interface. Tools like API Management helps in the control and governance of your APIs. Treating your APIs as standalone products, can help you to go further in your digital journey allowing you to easily fit in the API economy. Finally, I invite you to revisit with your team your approach to APIs and to notice the importance of not forgetting that the “I” in API stands for “Interface” and not for “Implementation”. 

api, api as a product, api management

Opinions expressed by DZone contributors are their own.

{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}