Driving API Team Collaboration with Blackbird

In my previous post in this series, I explored how Ambassador Blackbird helps to accelerate an API team’s development lifecycle. This post took the perspective of a single developer or team that needs to turn their API design into running code quickly. Blackbird provided code generation capabilities, along with single-command deployment of a running container to their infrastructure.

In this final article of the series, I’m going to explore how Blackbird enables teams to collaborate by exploring their features from a multi-team perspective. We will explore API discovery, adding a new API, exploring the API in the Blackbird web interface, and the options available to interact with the API from the command line and code.

Discovering Existing APIs

One of the challenging steps for a growing API practice is to manage their catalog of APIs. While some tools exist, they are often out-of-band of the developer workflow. With Blackbird , they provide a searchable catalog to locate a previously registered API.

Let’s imagine that I’m looking for a TODO List API. All I need to do is click on the ‘APIs’ feature, then search for a keyword, such as ‘TODO’:

In this example, the API already exists. As a developer, I can immediately start to look at the operations provided and explore the API from within the web interface. This helps to drive a consume-first culture, avoiding the need to build duplicate APIs by first searching for existing ones in the API catalog.

What happens if I don’t find the API I need? Then I probably need to create one of my own. I explored this flow as well.

Adding Your API to the Catalog

Since the first article focused more on the Align-Define-Design-Refine (ADDR) API design first process, let’s walk through the process of registering a new API with Blackbird based upon an existing OpenAPI Specification.

The first step is to upload the OpenAPI document:

After the document is parsed by Blackbird, it displays the details it discovered and allows me to make any adjustments necessary:

Once I click ‘Create API’, the API is added to the Blackbird catalog and available for exploration. I liked that it recognized the tags I assigned to the operations, and the option to immediately create a mock instance of the API. This supports my recommended flow of design, gain rapid feedback to refine your API design, and update the design prior to delivery.

Exploring the API

After the API is registered in the catalog, I am presented with an API details page in Blackbird. The page lists the servers and owner details from the OpenAPI document. Nice touch. While the owner email isn’t linked on the page, I like the idea that this was captured as I might be able to browse the catalog by API owner in the future by simply clicking the owner’s email.

Along with basic details, the list of endpoints (sometimes called API operations) are provided. The tags assigned to each operation are included, along with the summary. A ‘Preview’ button takes us to the details of the operation, where we will get to interact with our API:

Interacting with the API

Blackbird offers additional details about the API, including example requests and responses. This is similar to most API documentation tools. Since we chose to generate a mock instance when we registered the API, we can provide request details in the provided form and press the ‘Send API Request’ to see the response from the live mock instance:

Not only can you interact with the mock instance from this page, Blackbird also provides a cURL command that we can copy and paste into a shell:

If the owner of the API has deployed a running instance of the code to Blackbird, the API consumer can also work directly with the deployed instance instead of a mock. This supports the typical collaboration workflow between development teams, from discovery to viewing documentation and then interacting with the API to see how it works.

Wrapping Up

Blackbird proves to be a powerful tool for API teams, offering seamless collaboration from discovery to integration. Its API development workflow—from cataloging existing APIs to generating mock instances for testing—makes it easier for teams to avoid duplication and focus on consuming and enhancing APIs. Whether developers prefer a web interface or direct command-line interaction, Blackbird offers an efficient, consume-first culture across development teams. In addition, it encourages a design-first approach that keeps developers in a single workflow without the need to switch between various tools. I look forward to exploring Blackbird further as the product continues to evolve as they approach their general availability estimated date of October 1.