API First — Microservices

DZone 's Guide to

API First — Microservices

This article makes a case for designing your API as a first step, when it's easy to make changes, and shows how SwaggerHub makes this easy.

· Microservices Zone ·
Free Resource

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:

Image title

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:

Image title

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:

Image title

The complete generated Maven project code can be found here.

api ,integration ,java ,microservices ,open api ,spring boot ,swaggerhub

Opinions expressed by DZone contributors are their own.

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

{{ parent.tldr }}

{{ parent.urlSource.name }}