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, 2020 · 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:

  • Editors
  • Testing
  • Parsers
  • Mock Servers
  • Renderers
  • Converter

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:

  • Swagger: uses YAML (or JSON) format, with focus to be easy to parse and has wide options of extensions and integrations.
  • API Blueprint: comes with syntax close to Markdown, MSON and full support of all Apiary tooling and open-source tooling

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:

  • Enabled early discussions of API requirements: Following the design-first mentality, our teams can establish a premeditated plan of what and how to build.
  • Increased collaboration between stakeholders: Developers, product managers, and customers are able to review and discuss.
  • Improved quality and robustness of API Endpoints: Establishing a contract have allowed the team to test each other’s APIs before launch.
  • Reduced rework of UI builds: Spending time upfront to design, document, and test API endpoints have ensured UI-development readiness, resulting in fewer backend changes.

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.

Walmart Global Tech Blog

We’re powering the next great retail disruption.

Medium is an open platform where 170 million readers come to find insightful and dynamic thinking. Here, expert and undiscovered voices alike dive into the heart of any topic and bring new ideas to the surface. Learn more

Follow the writers, publications, and topics that matter to you, and you’ll see them on your homepage and in your inbox. Explore

If you have a story to tell, knowledge to share, or a perspective to offer — welcome home. It’s easy and free to post your thinking on any topic. Write on Medium

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store