Accelerating API Design with ADDR and Blackbird

I’ve been writing and teaching about the Align-Define-Design-Refine (ADDR) API design first process for many years. Along the way, I have made updates and improvements to the process. One thing that was lacking was a tool to complement the work of teams using ADDR. I’ve recently begun to explore a new product from Ambassador called Blackbird, which promises to accelerate the API lifecycle.

In this article, I’ll provide a brief review of the ADDR process, then use the artifacts from ADDR to help me design and mock the API. I’ll capture some tips and call out a few wishlist items that I hope Blackbird will incorporate into future releases.

Understanding the ADDR Process

The ADDR process is a methodology to guide organizations through the complexities of API design and implementation. It comprises four key phases:

1. Align: Establishing the strategic purpose of the API.
2. Define: Detailing the API’s capabilities.
3. Design: Creating the API’s structure and user experience.
4. Refine: Iterating based on feedback and testing.

Focusing on the Align and Define stages can significantly influence the success and efficiency of the API design process.

An example ADDR process

Improving the API design begins with crafting job stories to better align on the problem, job-to-be-done, and desired outcome(s):

Next, we expand the job stories into activity steps to better understand the work involved:

Finally, these insights are modeled as an API profile and associated resources:

The API is now ready to be designed using the best-fit API design style, such as REST, GraphQL, or gRPC. Let’s see how Blackbird, a new product offering from Ambassador, can further accelerate the API development process.

Using Blackbird with ADDR to accelerate API design

For those not familiar, Blackbird helps you accelerate your API development lifecycle by reducing the margin for errors, improving consistency and reusability, decreasing time-to-market, and driving positive business outcomes. It can work with an existing OpenAPI Specification document, or you can use their built-in AI bot to describe your API and let it generate the OpenAPI document automatically.

Generating an OpenAPI Specification using GenAI

Let’s try using our insights from ADDR to generate an OpenAPI specification. The first thing we need to do is craft a prompt using our existing ADDR artifacts. Here is the prompt I composed:

“Generate an OpenAPI Specification version 3.0.3 for a Bookstore API that allows customers to interact with bookstore operations such as listing books, searching by author or title, viewing book and cart details, adding or removing items from a cart, clearing the cart, and retrieving author details. Include paths for GET requests to list books, search books, and retrieve specific book or author details, as well as POST requests to create a cart, add items to a cart, and clear a cart, and DELETE requests to remove items from the cart. Define necessary parameters for each path, such as book IDs, item IDs, author IDs, category, and release date. Outline possible responses, including successful operations and common errors like missing books or authors. When adding an item to a cart, use a nested resource called items under the carts resource collection. Include operationIds on each path. Do not use inline schemas.”

This generated an OpenAPI Specification that reflected the previous work completed using the ADDR process:

While I would typically use multiple paragraphs or upload a complete specification, Blackbird’s AI bot only accepts a single paragraph currently. Hopefully, this will improve over time by offering a more robust set of options for prompt input.

Reviewing the API Design

Now that the API has been generated, it is automatically imported into my catalog of APIs. I can then review the API operations generated:

I then downloaded the OpenAPI specification and reviewed what it generated to make sure it has everything I want in my specification. Here is a screenshot of the generated OpenAPI Specification, with details collapsed:

Looks good so far! We have the right operations and even have our success and error responses. Plus, it generated schema components for reuse, so no need to do that ourselves. This saves hours of typing and troubleshooting and also avoids moving between a variety of tools, downloading and uploading artifacts along the way.

Refining your API design with mocks

The next step in ADDR is to refine the API using a mock of our design. This ensures our design includes everything our API consumers will need. Typically, I would jump to yet another tool to create a mock. With Blackbird, this is built in with a single click:

I’m then taken to the mocks section, where my mock implementation is created, launched, and ready. I now have a URL endpoint that I can use to make mock requests:

Using the mock URL endpoint provided, I appended /books to the URL and was able to send a GET request to my mock server and receive a response:

This mock helps me to see if I’m missing any resource properties and will go far to accelerate the API consumer’s work while the implementation is built out. In an upcoming release, Blackbird will offer customized mock responses. For now, crafting your own OpenAPI Specification with example values is the best way to get real-world data into the mocks.

Conclusion

I’ve been instructing individuals and teams on using the ADDR API design process for almost a decade. In that time, the process has helped teams to accelerate their API design and delivery lifecycle. The challenge has been finding a tool that can help take ADDR artifacts and drive API delivery.

With the addition of Blackbird, I can now accelerate the API design lifecycle by importing an existing OpenAPI document, using GenAI to produce an OpenAPI document, and see my API in action by generating and deploying a mock API with a single click. While it can do more than just help develop APIs, I’ll leave that for a future follow-up as I continue to dive into Blackbird to see how it can accelerate other areas of the API lifecycle.