Leveraging API Blueprint to Scale Application Development

Adopting an API description solution to encourage collaboration amongst teams to improve the API design lifecycle.

Ricky Huynh
Jan 14 · 4 min read

Communication is the key to any successful working relationship and you should establish a common language to drive that success. What do I mean by a common language? I’m referring to a method that exchanges clear and concrete information among the teams you’re working with or even the members of your own team.

Photo by Daniel McCullough on Unsplash

In application development, there are often different individuals who own specific areas of the code. Let’s take a Restaurant Finding app, for example. One team may build functions for the restaurant profile page; another team may work on search; and another may develop the UI. Without intelligible ways to share their work, integration within the teams will be highly inefficient.

I’ve been trying to tackle this challenge at Walmart Labs. My team is responsible for building UIs and we often faced issues with API designs during development — causing enormous amounts of rework. Check out my blog about Streamlining Frontend-as-a-Service for Backend Teams.

So, what can you do to scale application delivery across multiple teams? Welcome API Blueprint — a simple way to design, create, document, and test APIs.

Note: This blog was inspired by an internal presentation delivered by Idris Tarwala.

Team Collaboration with API Blueprint

What is API Blueprint?

API Blueprint is a design language for web APIs that offer a range of open-sourced tools. These tools help engineers throughout their development lifecycle, with features that include, but not limited to, the following:

Check out the full list of tools.

“The goal of API Blueprint is to decouple elements of API to enable modularity while encapsulating backend implementation behavior.” ¹

Why API Blueprint?

“API Blueprint is built to encourage dialogue and collaboration between project stakeholders, developers and customers at any point in the API lifecycle.” ¹

Again, the key to success is establishing a common language. API Blueprint gives you a common language to drive discussions around the API design and build out a data contract throughout the API lifecycle. Identifying changes to the API design early on is far less time consuming than making changes once development starts.

API Blueprint eliminates ambiguity between all stakeholders by providing tools that clearly document the APIs, render the documentation, and generate mock servers for testing and continuous development.

“Once your API Blueprint is in place everybody can test whether the implementation is living up to the expectations set in the contract.” ¹

Example Development Flow with API Blueprint

In the example above, the backend team designs, documents, and renders API definitions in HTML format for frontend teams. The backend team also builds mock servers and tests — enabling frontend teams to develop the UI with operable endpoints.

Get started with API Blueprint here.

Alternative Solutions

There are alternative solutions that offer the same benefits as API Blueprint, such as OpenAPI Specifications (Swagger). Both formats are open-sourced and have great community and tooling built around them. Key high-level differences between the two are:

The purpose of this blog is to describe an ideal API Lifecycle process that will work with any API description solution. The solution you select should depend on which format and toolset best matches your team’s skillset.

Impact of Adopting API Blueprint

Adopting API Blueprint has shifted our team towards a design-first development mentality. We have scaled our application development process and seen positive impact in the following areas:

I’m always looking for new ways to improve our process. If you have any suggestions or have had a similar experience, please share in the comment section below.

1: API Blueprint. Retrieved December 26, 2019 from https://apiblueprint.org/

Did you find this useful? Please recommend or share, and feel free to hit the clap button. 👏🏻 Follow me for future posts.


Using technology, data and design to change the way the world shops. Learn more about us - http://walmartlabs.com/

Ricky Huynh

Written by

Product Manager, UI/UX @ Walmart Labs


Using technology, data and design to change the way the world shops. Learn more about us - http://walmartlabs.com/

More From Medium

More from WalmartLabs

More from WalmartLabs


More from WalmartLabs

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade