Leveraging API Blueprint to Scale Application Development
Adopting an API description solution to encourage collaboration amongst teams to improve the API design lifecycle.
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.
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.
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.” ¹
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/
