Designing a high-quality API specification is not a trivial task. First of all, outlining the defining aspects of high-quality API design can be surprisingly difficult, as you will struggle to find a ready-made, one-size-fits-all solution for your projects independent of specific use cases or business requirements. At the same time, modern approaches for building products according to API-first design principles rank high-quality API specifications as vitally important, as they are crucial for the entire development process. Real-world examples and practical learnings can be of great assistance in establishing a fundamental understanding and avoiding the many pitfalls on the road to a successful and unified API vision. 

At Interhyp, we are currently on an ambitious journey to not only migrate existing legacy systems to a modern microservice architecture, but also to review and overhaul the current API strategy to pave the way for an even more successful future.  

When analyzing the status quo, various flaws were easily discovered: The existence of API guidelines that were more of a suggestion than a binding contract, a variety of non-uniform APIs which were overly reliant on an anti-corruption-layer for the integration with partner systems, as well as insufficiently defined roles and responsibilities for different stakeholders. Thus, the primary goal was to establish new guidelines and to define processes and provide tools that meaningfully supplement an API-first approach. In this regard, the primary areas of concern were standardization, automation as well as the definition of clear responsibilities.

The Three Building Blocks

To expedite standardization, various approaches were considered. Firstly, there will no longer be a distinction between internal and external API consumers. Instead, every service that is not strictly for internal use should provide a single API of a quality (in terms of documentation and clarity of design) such that it could be readily integrated with an external business partner’s system. Notably, the use of anti-corruption-layers is now deemed an exception rather than the norm. This focus on establishing a standard of quality is supported by reformulating the API guidelines and the slow introduction of mutually agreeable rules backed by automated processes to promote adherence.  

Secondly, reusable components are defined for commonly used business objects (e.g., address formats) or technical objects (e.g., the RFC 7807 error format). These components also serve as enhancement to the common look and feel of APIs by specifying terminology and wordings shared across business domains. 

The process of standardization simultaneously allows for and is aided by automation. Integrating tools like linters (we use Spectral) and automated API contract testing into CICD pipelines and IDEs (e.g., by means of annotation plugins) will not only improve the quality of APIs but also foster a culture of standardization through alignment towards common goals. The aim should be to transform the API guidelines from a cumbersome set of rules to a guide that facilitates API design and alleviates some of the burden of making design decisions by providing sensible standards.

Lastly, the roles and responsibilities of the different teams involved in the development process were revised and specified more clearly. Services were grouped into domains by their business function (e.g., a document domain) with specific teams having full ownership of the domain and its responsibilities. These teams design and implement the actual APIs and refer to the integration team for feedback. 

The integration team was tasked with the ownership of API management and governance. As this team is expected to have general knowledge of all domains, its role is also that of a proxy for business partners, reviewing APIs from their point of view and asserting their business requirements as well as writing consumer-driven contract tests. This team is not only responsible for managing the quality of APIs and ensuring their readiness, but they also define standards and automate relevant processes.

From these three building blocks, we at Interhyp are aiming to form our new common API vision in the upcoming months. As we progress on our journey, you can expect more blog articles on matters concerning modern API design and management. What is your opinion on this matter? Do you have any suggestions or recommendations? We look forward to receiving and responding to your feedback in the comments.