Practical Application of API-First in microservices development

Editor's Notes

• #4: APIs is how software systems communicate. In world of mass digitalization, APIs are, everywhere around us.
• #5: While in the past APIs were mostly used for external communication, the growing popularity of Microservice based architecture led to the explosion of APIs, both internal and externally facing.
• #6: Let us see what are the implications of replacing local communication with remote communication, when utilizing microservices architecture. While local API calls are usually statically linked at compile time, remote REST calls are loosely coupled, and with separate lifecycle. You can update the implementation or evolve is separately from the client. Latency and Overhead of Remote REST calls is incomparable to Local API calls. While in monolithic system basically data structures are in consistent in memory format, in remote REST communication Data is encoded and goes through various conversions. Although not discussed often, this threatens data integrity between the communicating parties. Local API is always available. Usually, local database transactions used to enforce database consistency even if the whole application crashes. This is not the case with remote REST calls, where the service might be down at any time, without any client information, whether the API call is processed Independent deployment, means we must watch out for incompatible or braking changes.. As distributed system is not deployed atomically.
• #7: Poor API Design besides the usual development productivity problems seems to amplify bad effect of all challenges, that come with remote communication. In many ways, poor APIs are direct consequence of lack of understanding of the implications of changing the media from local to remote calls and transport layer specifics. SOAP Efforts are one such example, where REMOTE Call Protocol was designed, with goal to be transport agnostic, and violating many of the transporting protocol principles like HTTP paradigms.
• #8: Good APIs allow clients to mitigate adequately most of the challenges of using remote APIs. For example, they are designed for idempotency, allow asynchronous processing of long executing operations or provide server-side filtering (minimizing transfer of unneeded data) and pagination. All this needs to be designed into the APIs.
• #9: Now that we set the tone of what do we expect from good APIs and what we don’t, let us dig into how do we build APIs and how it affects their quality ?
• #10: One of the most common ways of exposing APIs is using the Code First Approach. Implementation laid out based in requirements and is exposed as RESTful APIs. API Specification is produced as part of build process or at runtime based on the implementation Code is enhanced with additional annotation to facilitate API Generation API is byproduct of the implementation, as a result it is strongly influenced by it.
• #11: Huge part of the APIs used today are produced this way In some situations, this is considered good approach, like rapid prototyping This approach is preferred for speed of delivery, since no or little time is spent on API design and alignment The API Design is influenced by annotating the implementation Incompatible changes might happen often unintentionally. In most of the cases instead of fixing the implementation companies are introducing complex and expensive to maintain middleware as an effort to make the APIs usable, without refactoring the implementation.
• #12: While in the code-first approach APIs are somewhat a result of the implementation efforts, the API-First approach reverses the process in the opposite direction. Where the implementation effort is driven by API requirements. In order to structure the approach couple of principles apply when trying apply it. 1. The first Brainstorming phase is also relevant and quite related also to microservices design and consists of distinguishing the API grouping and Domain Models used by different APIs and their ownership. The effort here is mostly to make different APIs in the company, as much self contained as possible and loosely coupled. This will likely make them stable 2. Find out Use Cases for APIs and Establish API Stakeholders. Remember one of the principles of Good APIs is that they are Use Case centric. However, having no stakeholders will hardly tell you how well you match these. Find out what is the minimal context needed for fulfilling the use cases at hand. 3. Design APIs and define them using formal API Definition Language – Open API 3.0 is de-facto industry standard for defining RESTful APIs 4. To achieve API consistency and application of Best Practices, define style guides, do API developers have some guidance, when designing them. 5. API Governance can be achieved through Peer Reviews, Stakeholder feedback and static linting. 6. Automate all processes around API lifecycle management and make it accessible to all parties involved. API Publication , release generation of Client and Server-side artifacts should be automated. 7. Track and manage your APIs – check for redundancy and inconsistencies. 8. Create a central place for internal developers, where developers and various stakeholders can collaborate.
• #13: APIs are the face of your service! Getting Feedback as early as possible on your API might be highly influential to your implementation approach. Having formal API Specification, defined allows evaluating the API, even before the implementation is available using mocks and finding design issues. Inconsistencies and antipatterns are easily spotted and rectified. Reworking this in later stage, might be impossible, or done at great expense.
• #14: It is not actually all champaign and roses as implementing API-First comes with its own challenges. - For adopting API-First it is of outmost importance, that API Contract is defined using formal API Specification such as Open API 3.0and derive the implementation out of this contract. Developers need learn how to describe their APIs using formal API Definition language and the tools used for it. There is no way around that, although there are visually appeal to help with that. - Another important step is to identify stakeholders and use cases for these APIs, so feedback can be collected as early as possible. Ideally even before the implementation started. Often APIs and Services are being built, with the idea on the problems they are about to solve, but the stakeholders are involved very late in API design. When you have API in mind, be sure to have stakeholders in line for it, and ready to validate it. Usually, various tools are adopted with various appeal to different stakeholders, but not well integrated into the overall software development process. Making the tooling well integrated and streamlined, plays a big part into “Selling” the idea to Developers. Since for them this seems way more hassle than “quick and dirty” Code-First approach. Last, but not least, the “API Design Upfront” effort is confused with “Big Design Upfront” architecture approach condemned by Agilists and alike. That misconception it totally wrong, since getting early feedback and making sure Right Things Get Built the Right Way, avoids late and costly rework.