API First — Microservices

Designing your API first, you will be able to visualize how your API is going to be structured based on HTTP methods, and it will also facilitate discussion with your development teams, business users, and the rest of the stakeholders who wish to consume your API well before its implementation. This kind of discussion allows you to build user stories and generate high-level documentation describing the intent of the API that you are going to build. It also helps you to discover potential issues with respect to the API standards/approach that you started well before the development, and changes at that point can be done very quickly, as you haven’t started any implementation yet.

Nowadays, many organizations are geared towards microservices architecture as part of their IT transformations, and development is pretty parallel with agile teams. The API-first approach helps dev teams to work on a certain part of an API implementation, and helps to track progress transparently. It also enforces common API standards/approaches out of the box based on predefined templates, and all your APIs look very consistent, instead of each team defining APIs differently. In the early days, I experienced microservices development without API-first design and went through changes over time, as when I received new requirements to add more stuff onto the existing API.

There are several open source frameworks/tools that help you to define your API first with REST URIs/paths along with their payloads/headers for all HTTP methods. One of the popular open source frameworks is Open API (a.k.a. Swagger). With Open API, API design includes defining all REST paths, payload objects, headers, and documentation in YAML syntax (a superset of JSON and independent of any language), and with the help of SwaggerHub (Swagger editor), you can visualize/edit the YAML file. 

Here is an example of an API definitions spec that I created in YAML syntax.

The SwaggerHub/Swagger code editor looks like this:

Once API definitions are done, Swagger code gen generates both client and server code for many languages out of the box. You can see some of the languages in the below screenshot:

I selected the Java/Spring Boot option and Swagger code gen properly generated a microservice project with all dependencies configured. Here is what the generated controller code based on Swagger file definitions looks like:

The complete generated Maven project code can be found here.