DZone
Thanks for visiting DZone today,
Edit Profile
  • Manage Email Subscriptions
  • How to Post to DZone
  • Article Submission Guidelines
Sign Out View Profile
  • Post an Article
  • Manage My Drafts
Over 2 million developers have joined DZone.
Log In / Join
Refcards Trend Reports Events Over 2 million developers have joined DZone. Join Today! Thanks for visiting DZone today,
Edit Profile Manage Email Subscriptions Moderation Admin Console How to Post to DZone Article Submission Guidelines
View Profile
Sign Out
Refcards
Trend Reports
Events
Zones
Culture and Methodologies Agile Career Development Methodologies Team Management
Data Engineering AI/ML Big Data Data Databases IoT
Software Design and Architecture Cloud Architecture Containers Integration Microservices Performance Security
Coding Frameworks Java JavaScript Languages Tools
Testing, Deployment, and Maintenance Deployment DevOps and CI/CD Maintenance Monitoring and Observability Testing, Tools, and Frameworks
Partner Zones AWS Cloud
by AWS Developer Relations
Culture and Methodologies
Agile Career Development Methodologies Team Management
Data Engineering
AI/ML Big Data Data Databases IoT
Software Design and Architecture
Cloud Architecture Containers Integration Microservices Performance Security
Coding
Frameworks Java JavaScript Languages Tools
Testing, Deployment, and Maintenance
Deployment DevOps and CI/CD Maintenance Monitoring and Observability Testing, Tools, and Frameworks
Partner Zones
AWS Cloud
by AWS Developer Relations
Securing Your Software Supply Chain with JFrog and Azure
Register Today

Trending

  • How To Use Pandas and Matplotlib To Perform EDA In Python
  • Never Use Credentials in a CI/CD Pipeline Again
  • Chaining API Requests With API Gateway
  • How To Use Geo-Partitioning to Comply With Data Regulations and Deliver Low Latency Globally

Trending

  • How To Use Pandas and Matplotlib To Perform EDA In Python
  • Never Use Credentials in a CI/CD Pipeline Again
  • Chaining API Requests With API Gateway
  • How To Use Geo-Partitioning to Comply With Data Regulations and Deliver Low Latency Globally
  1. DZone
  2. Data Engineering
  3. Databases
  4. API First — Microservices

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.

Sam Kyatham user avatar by
Sam Kyatham
·
Aug. 08, 17 · Opinion
Like (5)
Save
Tweet
Share
8.09K Views

Join the DZone community and get the full member experience.

Join For Free

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 microservice Open source

Opinions expressed by DZone contributors are their own.

Trending

  • How To Use Pandas and Matplotlib To Perform EDA In Python
  • Never Use Credentials in a CI/CD Pipeline Again
  • Chaining API Requests With API Gateway
  • How To Use Geo-Partitioning to Comply With Data Regulations and Deliver Low Latency Globally

Comments

Partner Resources

X

ABOUT US

  • About DZone
  • Send feedback
  • Careers
  • Sitemap

ADVERTISE

  • Advertise with DZone

CONTRIBUTE ON DZONE

  • Article Submission Guidelines
  • Become a Contributor
  • Visit the Writers' Zone

LEGAL

  • Terms of Service
  • Privacy Policy

CONTACT US

  • 600 Park Offices Drive
  • Suite 300
  • Durham, NC 27709
  • support@dzone.com

Let's be friends: