From ADDR Design to Development with Blackbird

In my first post in this series, I explored how Ambassador Blackbird helps with supporting the Align-Define-Design-Refine (ADDR) API design first process. I found that Blackbird helped me to transform the ADDR artifacts into an API design using their AI bot, then generate a mock implementation without the need to write any code.

While ADDR helps teams to deliver an API design that is ready for delivery, that doesn’t mean that we are done. We still need to code the API implementation, integrate it with other developers, and debug the API when we encounter problems.

In this article, I’ll share my findings of how Blackbird supports generating boilerplate API code (in GoLang) and also enables remote development, debugging, and integration. This will extend the ADDR process into the delivery phase of the API lifecycle.

Moving from Mocks to API Implementation

One of the challenges I see teams encounter when transitioning from API design to delivery is the need to shift between a variety of tools. While there are existing code generators that exist to help automate the creation of boilerplate code, developers must spend time finding a code generator and then figuring out how to install it locally as part of their tool chain. This can slow down the flow of development.

Blackbird offers a built-in code generator with initial support for the Go Programming Language from their command line tool (CLI). The code generator is open source and can be used as a foundation to support generating APIs using your own favorite patterns and practices in Go, or used as a template for your own favorite language and framework.

Since we generated the OpenAPI document using the Blackbird AI feature, our OpenAPI document isn’t on our local laptop. All we have to do is download the generated OpenAPI document from Blackbird to start generating code from the CLI. I did this from their web interface already, but if you are following along then you will need to ensure you have your document stored locally.

To get started with the Blackbird generator, I verified that I had Docker installed locally. Then, I installed their CLI and then used their usage guide to help me run the generator:

blackbird code generate -s ADDR-bookstore-api.json -t go -o bookstore-api

To generate the boilerplate API code, the CLI asks a few specific questions. The usage guide helped me to understand how best to answer these questions. Below is a screenshot showing how the full process worked:

The generated code is modular, with a clean separation between the schema objects that represent our resources and the supporting code to handle each operation. By default, the code returns a 501 Not Implemented response as a placeholder.

Now that we have generated a boilerplate API implementation within Blackbird, let’s run it locally.

Running the Generated Code Locally

Now, it is time to launch our generated code locally to see it running. We will cd into the folder that was generated and use the standard go run command to start:

go run cmd/bookstore-api/main.go

Here is what we will see:

I then pointed my browser to http://localhost/books to see that it was working:

We can check the output logs from our local running instances to see that it reached our generated code successfully:

Great! Everything is working fine so far. At this point, we can start adding implementation details. As we do this, we will want to make our API remotely accessible for others to use. Let’s do this next using Blackbird’s relay service.

Running the Generated API Code Remotely

As the generated code is replaced with working code, you may want to obtain feedback on how the API is behaving. Typically this would require installing yet-another-tool to relay the local API responses to another developer. Blackbird offers this as part of their solution, keeping us from installing a separate tool.

Using the usage guide, I was able to use the Blackbird CLI tool to build it using Docker, register the API with Blackbird, and obtain a URL to try out the API from anywhere:

blackbird code run addr-bookstore-api --dockerfile Dockerfile --context . --local-port 80

You will see the full process, from build to packaging into a container, and registering the API on your console. When it has completed the process, it will provide the URL and let you know it is running locally, ready to accept inbound requests:

I then composed a URL using the base URL provided, appending /books to the end to verify that everything is working correctly:

For team members that want to use the mock, they can login to Blackbird and click on the Code screen from the left navigation bar to find the URL:

Nice! I can now continue with the typical development work, then make it available for feedback and early integration as needed. However, this feature only works if our laptop is online. So, let’s now explore deploying our API to Blackbird’s dedicated environment.

Deploying our API to a Dedicated Environment

The last thing that we want to explore is deploying our API to a dedicated Blackbird environment. This will allow team members and API consumers to access the API using a unique URL. Unlike the remote access we just explored, this approach doesn’t require a developer laptop to be running to access the API. Instead, Blackbird hosts a containerized instance of your API for easy access at any time during the API development lifecycle.

blackbird deployment create addr-bookstore-api --dockerfile Dockerfile --context .

Wrap-up

To recap our progress so far, we:

1. Turned our ADDR-based artifacts into an OpenAPI Specification with the help of Blackbird’s API bot (see previous article)
2. Produced a mock implementation based on the OpenAPI document so that we can explore the API before we start writing code (see previous article)
3. Generated an API implementation in Go using the Blackbird code generator
4. Implemented each API operation by running locally, then using Blackbird’s relay capabilities to make them available for our team and API consumers for quick testing and feedback
5. Deployed our API to Blackbird for developer availability of our API implementation

We did this all in one tool, without the need to copy-and-paste or write automation scripts to manage our API development lifecycle.

I’m looking forward to seeing what generators the community and the Blackbird team produce in the future. Starting with Go was a good idea, though I would expect Spring Boot, Node.js, and other frameworks to be supported, as these are commonly encountered in enterprises today.