DEV Community: Matt Voget

Host a Reverse Proxy in Seconds

Matt Voget — Mon, 23 Sep 2024 21:37:28 +0000

Need a publicly accessible reverse proxy? Want to skip testing with localhost? Blackbird has an easy solution.

Setting up the Proxy

First let’s configure a simple reverse proxy with nginx using the following nginx.conf:

server {
    listen 80;
    location / {
        proxy_pass "https://httpbin.org/";
    }
}

All requests sent to this server will proxy out to httpbin.org — a nice tool for developing and testing this proxy with downstream servers/APIs.

Next, we’ll define a simple Dockerfile that uses our ngnix configuration to build an image:

FROM nginxinc/nginx-unprivileged

COPY nginx.conf /etc/nginx/conf.d/default.conf

EXPOSE 80

USER 1000

CMD ["nginx", "-g", "daemon off;"]

Hosting the Proxy with Blackbird

After installing the Blackbird CLI, we can publicly host this reverse proxy with a Blackbird deployment:

blackbird deployment create proxy -d Dockerfile -c .
  ✔ input validated
  ✔ environment is ready
  ✔ no matching mock instance found
  ✔ image successfully built
  ✔ image successfully pushed
  ✔ checking existing deployments
  ✔ creating application for deployment
  ✔ application deployment created
+-------+------------+----------+---------------------------------------------------------+
| NAME  | TYPE       | STATUS   | URL                                                     |
+-------+------------+----------+---------------------------------------------------------+
| proxy | deployment | Ready    | https://matts-org-a0696.blackbird-relay.a8r.io/proxy/   |
+-------+------------+----------+---------------------------------------------------------+

Blackbird gave us a public host that is running our reverse proxy in a container - let’s try it out:

curl --request POST -d '{"message":"hello"}' \
https://matts-org-a0696.blackbird-relay.a8r.io/proxy/post

{
  "args": {}, 
  "data": "{\"message\":\"hello\"}", 
  "files": {}, 
  "form": {}, 
  "headers": {
    "Accept": "*/*", 
    "Content-Length": "19", 
    "Content-Type": "application/json", 
    "Host": "httpbin.org", 
    "User-Agent": "curl/8.6.0"
  }, 
  "json": {
    "message": "hello"
  }, 
  "url": "https://httpbin.org/post"
}

Just like that, our reverse proxy is live and hosted 🚀

Happy proxying!

Mocking an AI Chatbot API with Blackbird

Matt Voget — Mon, 23 Sep 2024 21:25:58 +0000

I’ve been developing APIs for years. In every API project, I face the same struggle of needing mocks, but spending too much time setting up, hosting, and maintaining them. I’d rather spend that time implementing the APIs or client code. Mocking is important — it’s useful in development, debugging, testing, and can power the “try-it-out” portion of an API’s docs.

As a software engineer I’ve used a variety of mocking tools and libraries including Mock Server, SOAP UI, and Mock Service Worker. These tools are helpful, and can be quick to setup for personal use, but still require a lot of infrastructure and setup to effectively use on a dev team or in CI/CD scenarios. Every software company I’ve worked at had a different home-grown way of configuring and hosting mocks for APIs, and usually the hosting part was managed by a separate DevOps or infra team.

Blackbird is a new tool I helped create at Ambassador that among other things can quickly create shareable mock instances of APIs and host them in a SaaS environment. This post will walk through an example of using Blackbird to setup mocking on an AI chatbot application that both consumes and implements an API.

AI Chatbot Example

Let’s assume the following scenario: I want to create an AI chatbot app that uses a microservice to consume OpenAI’s API. The microservice will host a few RESTful endpoints for configuring and sending chat requests over to OpenAI and sending back responses from the LLM. Here is a diagram of what this will look like:

I can already tell that I’ll want a mock server setup for the Chatbot API microservice, which will enable development and testing of the chatbot UI. But I will also need a mock server setup against the OpenAI API — this will allow for development and testing of my microservice without relying on live (and potentially expensive) requests to OpenAI’s API.

Mocking the Chatbot API

Let’s start with my microservice. As with most APIs, I like to start with an Open API spec to serve as my contract for this microservice. Blackbird has it’s own AI-powered API spec creator that I will use as a starting point. After logging into Blackbird and selecting “Create new API” I can create my spec using the following prompt:

I want to create an API for a microservice for my AI chatbot. I want my API to have a post endpoint called chat that accepts a request body with a single property for a prompt and handles a response with a single property for a chat message. I also want a get endpoint called model for information about the AI model being used and a post endpoint to change models.

And here is Blackbird’s response:

{
  "openapi": "3.0.1",
  "info": {
    "description": "API for AI Chatbot Microservice",
    "title": "AI Chatbot API",
    "version": "1.0.0"
  },
  "tags": [
    {
      "name": "Chat"
    },
    {
      "name": "Model"
    }
  ],
  "paths": {
    "/chat": {
      "post": {
        "tags": [
          "Chat"
        ],
        "summary": "Initiate a chat with the AI chatbot",
        "operationId": "chat",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ChatRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ChatResponse"
                }
              }
            }
          },
          "404": {
            "description": "Not Found"
          },
          "500": {
            "description": "Internal Server Error"
          }
        }
      }
    },
    "/model": {
      "get": {
        "tags": [
          "Model"
        ],
        "summary": "Get information about the AI model being used",
        "operationId": "getModel",
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ModelInfo"
                }
              }
            }
          },
          "404": {
            "description": "Not Found"
          },
          "500": {
            "description": "Internal Server Error"
          }
        }
      },
      "post": {
        "tags": [
          "Model"
        ],
        "summary": "Change the AI model being used",
        "operationId": "changeModel",
        "responses": {
          "200": {
            "description": "Successful response"
          },
          "404": {
            "description": "Not Found"
          },
          "500": {
            "description": "Internal Server Error"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ChatRequest": {
        "type": "object",
        "properties": {
          "prompt": {
            "type": "string"
          }
        },
        "required": [
          "prompt"
        ],
        "additionalProperties": false
      },
      "ChatResponse": {
        "type": "object",
        "properties": {
          "chatMessage": {
            "type": "string"
          }
        },
        "required": [
          "chatMessage"
        ],
        "additionalProperties": false
      },
      "ModelInfo": {
        "type": "object",
        "properties": {
          "modelName": {
            "type": "string"
          },
          "modelVersion": {
            "type": "string"
          }
        },
        "required": [
          "modelName",
          "modelVersion"
        ],
        "additionalProperties": false
      }
    }
  }
}

Perhaps I’ll make a few tweaks, but it actually produced a robust spec for me. As with most LLMs the quality of the output is dependent upon the quality of the input prompt. It’s still nice that Blackbird could do a little prompt engineering for me to create a valid OAS file versus using ChatGPT.

Blackbird also gave me the ability to download my spec, which I will put into my code repo. As a bonus, it launched a mock server:

Within seconds I see a public URL for a mock server on my chatbot API. Let’s test it out by curling the endpoints:

curl -s https://default-blackbird-matts-organization-50147-0.blackbird-relay.a8r.io/ai-chatbot-api/model | jq
{
  "modelName": "in Duis ex aute adipisicing",
  "modelVersion": "ullamco"
}

curl -s \
-H "Content-Type: application/json" \
--request POST \
--data '{"prompt": "Hello chatbot API!"}' \
https://default-blackbird-matts-organization-50147-0.blackbird-relay.a8r.io/ai-chatbot-api/chat | jq

{
  "chatMessage": "mollit ex nisi"
}

A few nice things to note: the mock URL that Blackbird provided is publicly accessible, which is great for collaboration, but Blackbird also supports locking it down with an API key in case I wanted to keep the mock URL internal to my team.

Now with the Chatbot API mocked, development on the Chatbot app frontend can commence while the API is being implemented.

Mocking OpenAI’s API

Before we implement the Chatbot API, I also want to mock out the interface between the Chatbot API and the external OpenAI API. Blackbird has already cataloged a set of 3rd party APIs - OpenAI being one of them. In just a few clicks I can have a mock instance of OpenAI up and running:

Alternatively, I can download the Blackbird CLI to catalog and mock APIs. The Blackbird Quickstart guide has instructions on downloading the CLI. Once downloaded, I can login to connect to the same Blackbird environment I was using in on the website.

From the CLI, I can spin up another mock server in a single command:

blackbird mock create openai -s openai_api.yaml
  ✔ input validated
  ✔ spec file validated as an OpenAPI 3.0.x spec
  ✔ checking existing deployments
  ✔ environment is ready
  ✔ creating application for deployment
  ✔ uploading specification file
  ✔ mock instance created
  ✔ mock instance is ready, URL: https://default-blackbird-matts-organization-50147-0.blackbird-relay.a8r.io/ai-chatbot-api/

Once again, the OpenAI mock server is ready in seconds with a public URL. Let’s test out the chat completion endpoint:

curl -s \
-H "Content-Type: application/json" \
--request POST \
--data '{
"model": "gpt-3.5-turbo",
"messages": [ 
  { 
    "role":"system", 
    "content": "You are a helpful assistant."
  },
  { 
    "role":"user",
    "content":"Hello!"
  }
]
}' \
https://matts-org-ec914.blackbird-relay.a8r.io/openai/chat/completions

{"type":"NO_PATH_MATCHED_ERROR","title":"Route not resolved, no path matched","status":404,"detail":"The route /v1/chat/completions hasn't been found in the specification file"}%  mattvoget@a2251-11 Downloads % curl -s -H "Content-Type: application/json" --request POST --data '{"model": "gpt-3.5-turbo", "messages": [ { "role":"system", "content": "You are a helpful assistant."}, { "role":"user", "content":"Hello!" } ] }' https://default-blackbird-matts-organization-50147-0.blackbird-relay.a8r.io/openai/chat/completions | jq
{
  "type": "UNAUTHORIZED",
  "title": "Invalid security scheme used",
  "status": 401,
  "detail": "Your request does not fullfil the security requirements and no HTTP unauthorized response was found in the spec, so Spectra is generating this error for you.",
  "headers": {
    "WWW-Authenticate": "Bearer"
  }
}

Testing this endpoint gave me back a 401 error saying that my request wasn’t properly formed — and sure enough I forgot to include a header to pass a bearer token (something I’ll need to remember when implementing the code to consume this API).

curl -s \
-H "Content-Type: application/json" \
-H "Authorization: Bearer abc123" \
--request POST \
--data '{
"model": "gpt-3.5-turbo",
"messages": [ 
  { 
    "role":"system", 
    "content": "You are a helpful assistant."
  },
  { 
    "role":"user",
    "content":"Hello!"
  }
]
}' \
https://matts-org-ec914.blackbird-relay.a8r.io/openai/chat/completions

{
  "choices": [
    {
      "finish_reason": "function_call",
      "index": 27121527,
      "message": {
        "role": "assistant",
        "content": "est dolore",
        "function_call": {
          "name": "veniam elit ea dolore minim",
          "arguments": "velit elit ut occaecat",
          "adipisicing_42": -74878644.6990763
        },
        "tool_calls": [
          {
            ...
          },
          ...
        ]
      },
      "logprobs": {
        "content": null
      }
    },
    {
      "finish_reason": "content_filter",
      "index": 42608321,
      "message": {
        ...
      },
      "logprobs": null,
      "est573": 33824876.70214461,
      "incididunt_1f3": 82999925.43383965
    }
  ],
  "created": 17226006,
  "id": "dolore officia dolor occaecat",
  "model": "irure adipisicing reprehenderit",
  "object": "chat.completion",
  "service_tier": "default",
  "system_fingerprint": "dolor ut",
  "usage": {
    "ad5": -10679086,
    "completion_tokens": 96235456,
    "inc0d": -845831.3006245494,
    "non_6": -10729837,
    "prompt_tokens": -12780052,
    "reprehenderit_e5a": "sint sunt",
    "sed_74_": false,
    "total_tokens": -31534344
  }
}

Much better. And in looking at this mock response I also notice a few goodies:

There are Lorem Ipsum properties in the response, such as "nullaf": "consequat", - these are added because the OpenAI spec file indicates additionalProperties: true in the Chat Completion response. The mock server automatically added them for me which is great for testing.
The choices array in the response gives a varying number of elements each time I curl the endpoint. Also super useful in testing.

This mock server will now enable development on my chatbox API microservice without me needing to call out to the live OpenAI API.

Wrapping it up

Let’s use Blackbird to review the state of APIs and mocks for my app. First let’s see what APIs we’ve cataloged in Blackbird:

blackbird api list
  ✔ getting a list of available APIs
+----------------+----------------+------------------+------------+
| API NAME       | SLUG NAME      | SPEC FILE        | CREATED BY |
+----------------+----------------+------------------+------------+
| AI Chatbot API | ai-chatbot-api | chatbot_api.json | Matt       |
+----------------+----------------+------------------+------------+

This only shows the Chatbot API spec, but that was because I didn’t upload the OpenAI spec into Blackbird’s catalog, but instead created it ad-hoc with the downloaded spec file. Uploading it to Blackbird is also easy:

blackbird api create openai -s openai_api.yaml 
  ✔ openapi file loaded
  ✔ input validated as an OpenAPI 3.0.x spec
  ✔ API created
+----------+-----------+-----------------+------------+
| API NAME | SLUG NAME | SPEC FILE       | CREATED BY |
+----------+-----------+-----------------+------------+
| openai   | openai    | openai_api.yaml | Matt       |
+----------+-----------+-----------------+------------+

blackbird api list                            
  ✔ getting a list of available APIs
+----------------+----------------+------------------+------------+
| API NAME       | SLUG NAME      | SPEC FILE        | CREATED BY |
+----------------+----------------+------------------+------------+
| AI Chatbot API | ai-chatbot-api | chatbot_api.json | Matt       |
| openai         | openai         | openai_api.yaml  | Matt       |
+----------------+----------------+------------------+------------+

The benefit here is now I can re-launch a mock instance without needing a local copy of the spec. I can now reference that spec by the API name through Blackbird.

Next let’s review our mock servers:

blackbird mock list                          
+---------------------+------+--------+--------------------------------------------------------------------------------------------------+------+
| NAME                | TYPE | STATUS | URL                                                                                              | USER |
+---------------------+------+--------+--------------------------------------------------------------------------------------------------+------+
| AI Chatbot API Mock | Mock | Ready  | https://default-blackbird-matts-organization-50147-0.blackbird-relay.a8r.io/ai-chatbot-api-mock/ | Matt |
| openai              | Mock | Ready  | https://default-blackbird-matts-organization-50147-0.blackbird-relay.a8r.io/openai/              | Matt |
+---------------------+------+--------+--------------------------------------------------------------------------------------------------+------+

Both are live and serving up mock responses. As I mentioned earlier, I can use the Chatbot API mock to help start development and testing on the Chatbot UI. And I also have the OpenAI API mock to begin work on the Chatbot API. This is exactly what I need to get started building my AI chatbot app with a team of developers.

Key Takeaways

Blackbird gave me two easy ways to catalog and mock APIs — either from the UI or from the CLI
Each mock server has an out-of-the-box public URL. This is by far the biggest time saver for me; manually setting up the infra would’ve taken hours and is not something in my wheelhouse as an app developer.
Related to the point above, I don’t need to worry about maintaining the infra to host additional mock servers, or tear down existing ones. Blackbird does the hosting for me.
Blackbird’s AI helper for quickly creating an API spec is very handy. Without it, I’d be stumbling through JSON/YAML or using a clunky form editor like SwaggerHub.
Finally (and a somewhat subtle point), using Blackbird as a CLI tool means I can script it into things like a CI/CD pipeline. When these spec files change in a code repo, it will be easy to auto-update their mocks. I will explore this case in a future blog post.

Mocking is still something I dread, but Blackbird makes it quick and painless, especially when it comes to setting up the hosting infra.

Webhook Testing with Blackbird

Matt Voget — Thu, 19 Sep 2024 15:13:17 +0000

If you've built integrations with 3rd party applications such as Stripe, PayPal, or GitHub chances are you've had to worry about handling webhooks. As a software developer it can be tricky to test webhook handling, because it relies on the 3rd party app to send a request to your API server - and in development your server is usually running at localhost.

In this post, I'll show how you can use Blackbird to quickly create a public URL for testing webhooks and show how it can also help debug webhook requests to your server.

Example: GitHub Commit Tracker

In this example, I'll be setting up a server that handles webhook requests from GitHub. Let's pretend I'm building a simple application that tracks anytime someone pushes a commit to a repo. You can follow along by cloning the Commit Tracker App written in Go.

git clone https://github.com/matty-v/commit-tracker
cd commit-tracker
go run cmd/commit-tracker/main.go

Test out the webhook endpoint by sending a POST request:

curl --request POST -d '{
  "ref":"refs/heads/main",
  "commits":
  [
    {
      "id":"abc123",
      "message":"Updated a file",
      "timestamp":"2024-09-18T00:00:00-06:00",
      "author":
      {
        "email":"test@example.com",
        "name":"Some Committer"
      }
    }
  ]
}' localhost/v1/webhook

It works locally, but the real test will be if it can handle an actual webhook from GitHub. This is where Blackbird comes in.

Setting up Blackbird

Follow the steps to install the Blackbird CLI on your laptop
Login to Blackbird: blackbird login - this will also provision a personal remote environment that you can use for testing

Testing the webhook with Blackbird code run

Instead of using go run I'll issue the following Blackbird command:

blackbird code run commit-tracker -d Dockerfile -c . -l 80

✔ image successfully built
✔ connected to Matt's organization blackbird environment 0
✔ temporary instance created
+----------------+------+--------+----------------+---------------------------------------------------------------------------------------------+------------+
| NAME           | TYPE | STATUS | APIKEY HEADERS | URL                                                                                         | CREATED BY |
+----------------+------+--------+----------------+---------------------------------------------------------------------------------------------+------------+
| commit-tracker | Code | Ready  |                | https://default-blackbird-matts-organization-5b603-0.blackbird-relay.a8r.io/commit-tracker/ | Matt Voget |
+----------------+------+--------+----------------+---------------------------------------------------------------------------------------------+------------+
✔ type <ctrl>-C to end...

Here is what Blackbird did behind the scenes:

Containerized my app and is running it in Docker on my local machine, exposing port 80
Generated a public URL in my personal remote environment
Actively routing traffic from the public URL directly to the local container

Now if I send that same curl command to test the webhook using the Blackbird provided URL I can see that my local server is responding the same way!

curl --request POST -d '{
  "ref":"refs/heads/main",
  "commits":
  [
    {
      "id":"abc123",
      "message":"Updated a file",
      "timestamp":"2024-09-18T00:00:00-06:00",
      "author":
      {
        "email":"test@example.com",
        "name":"Some Committer"
      }
    }
  ]
}' https://<my-env>.blackbird-relay.a8r.io/commit-tracker/v1/webhook

Be sure to replace <my-env> with the specific name of your environment as provided by Blackbird.

Let's go over to GitHub now to setup and test the webhook from the repo whose commits I wish to track. I can do this by navigating to Settings > Webhooks > add webhook

The Payload URL is the endpoint where GitHub will deliver the webhook request. Use the URL provided by Blackbird (e.g. https://<my-env>.blackbird-relay.a8r.io/commit-tracker/v1/webhook). Also be sure to check the "send me everything" option to get commit data.

With the webhook created, you can now test it out by making commits on the repo and see that your locally running code is handling it!

2024-09-18T21:02:30Z INF commit-tracker server is starting up
2024-09-18T21:02:30Z INF starting commit-tracker server, address: :80
2024-09-18T21:03:06Z INF POST /v1/webhook 200 729.608µs
[{{matt.voget@gmail.com Matt Voget} eec15... Update README.md 2024-09-18T12:05:32-06:00}]

When I'm done testing, I can ctrl-c on the command line to end the Blackbird code run session and kill the public URL.

Debugging webhooks with Blackbird

Let's pretend that I wasn't perfect and accidentally introduced a bug in my webhook handler code. I can use Blackbird to attach a debugger to my code to step through breakpoints as the webhook is being received.

To follow along, you can uncomment the //decoder.DisallowUnknownFields() line in handlers.go in the commit tracker code:

// HandleHandleWebhook handles parsing input to pass to the HandleWebhook operation and sends responses back to the client
func (h *APIHandler) HandleHandleWebhook(w http.ResponseWriter, r *http.Request) {
  var err error
  reqBody := GitHubWebhook{}
  decoder := json.NewDecoder(r.Body)
  decoder.DisallowUnknownFields()

This will make the handler reject webhook requests where the payload does not match the GitHubWebhook schema in the commit-tracker code. Perhaps you develop and test against a mocked GitHub client sending webhooks without all the payload fields. You may find your code working in dev and test, but failing when it hits production!

Here's how to use Blackbird to debug this problem:

blackbird code debug commit-tracker -d Dockerfile -c . -l 80

Once more, Blackbird containerized my code, but this time it followed instructions in the Dockerfile to build the image with debug symbols and expose port 2345 for a debugger to attach to.

In VSCode, I defined a launch.json debugger config with instructions to attach at that port:

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Connect to server",
            "type": "go",
            "request": "attach",
            "mode": "remote",
            "port": 2345,
            "host": "127.0.0.1"
        }
    ]
}

Now that I have attached the debugger, I can once more deliver a webhook from GitHub to the same public URL: https://<my-env>.blackbird-relay.a8r.io/commit-tracker/v1/webhook

This time, I can hit breakpoints and step through my code to see what's happening

Not only can I test webhooks with Blackbird, but I can also debug any issues directly from my IDE.

Notes on Security

Unlike other tools out there, Blackbird does not use tunneling to open traffic from the public URL to your localhost, nor will it modify your local machine's host network or DNS. It instead will leverage Docker's local container networking to establish a secure connection to the remote host - think of it like a mini-VPN. Out of the box, this significantly decreases the attack surface area for malicious actors who get access to the public URL.

Also, Blackbird has an ability to pass a custom-defined API key to blackbird code run and blackbird code debug commands. This will protect your public URL from being used by anyone who does not pass that key as a header in a request. To find out more, read the docs around securing Blackbird instances.

Wrapping Up

In this guide I showed how you can use the Blackbird CLI to test webhooks by using the blackbird code run and blackbird code debug commands. Try it yourself by creating a Blackbird account and downloading the CLI today!

Can AI build a deployable API?

Matt Voget — Mon, 16 Sep 2024 20:56:30 +0000

Yes! And can it do so in 5 minutes? Also yes!

By chaining a few concepts together it’s possible to use AI to generate a fully functional and deployable API in no time. Here’s how:

Create an OAS file by chatting with an AI
Use the OAS file as in input to a server-side API code generator
Validate the generated API code by deploying it into a k8s environment

AI Generated OAS Files (1 Minute)

Using AI is a great way to generate an OAS file. But like any interaction with AI, you get out what you put in, which is where a little prompt engineering can go a long way. Fortunately tools like Blackbird have done that prompt engineering to quickly create valid OAS files.

Here’s a prompt I used in Blackbird to create API spec for a fictional AI Chatbot:

I want to create an API for my AI chatbot. I want my API to have an endpoint for submitting a chat message and endpoints for getting and setting a model.

{
  "openapi": "3.0.1",
  "info": {
    "title": "AI Chatbot API",
    "description": "API for interacting with an AI chatbot, allowing users to submit chat messages and manage AI models.",
    "version": "1.0.0",
    "contact": {
      "name": "API Support",
      "url": "https://support.example.com",
      "email": "support@example.com"
    }
  },
  "servers": [
    {
      "url": "https://api.example.com/v1",
      "description": "Production server"
    }
  ],
  "tags": [
    {
      "name": "Chat",
      "description": "Operations related to chat messages"
    },
    {
      "name": "Model",
      "description": "Operations related to AI models"
    }
  ],
  "paths": {
    "/chat/messages": {
      "post": {
        "operationId": "submitChatMessage",
        "tags": [
          "Chat"
        ],
        "summary": "Submit a chat message to the AI chatbot",
        "description": "This endpoint allows users to send a message to the AI chatbot and receive a response.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ChatMessage"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful response with the chatbot's reply",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ChatResponse"
                }
              }
            }
          },
          "404": {
            "description": "Chatbot not found"
          },
          "500": {
            "description": "Internal server error"
          }
        }
      }
    },
    "/model": {
      "get": {
        "operationId": "getModel",
        "tags": [
          "Model"
        ],
        "summary": "Retrieve the current AI model",
        "description": "This endpoint retrieves the currently set AI model.",
        "responses": {
          "200": {
            "description": "Successful response with the current model",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Model"
                }
              }
            }
          },
          "404": {
            "description": "Model not found"
          },
          "500": {
            "description": "Internal server error"
          }
        }
      },
      "put": {
        "operationId": "setModel",
        "tags": [
          "Model"
        ],
        "summary": "Set a new AI model",
        "description": "This endpoint allows users to set a new AI model.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Model"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful response indicating the model has been set"
          },
          "404": {
            "description": "Model not found"
          },
          "500": {
            "description": "Internal server error"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ChatMessage": {
        "type": "object",
        "required": [
          "message"
        ],
        "properties": {
          "message": {
            "type": "string",
            "description": "The message to send to the chatbot.",
            "example": "Hello, how are you?"
          }
        },
        "additionalProperties": false
      },
      "ChatResponse": {
        "type": "object",
        "properties": {
          "response": {
            "type": "string",
            "description": "The response from the chatbot.",
            "example": "I'm doing well, thank you!"
          }
        },
        "additionalProperties": false
      },
      "Model": {
        "type": "object",
        "required": [
          "modelName"
        ],
        "properties": {
          "modelName": {
            "type": "string",
            "description": "The name of the AI model.",
            "example": "gpt-3.5-turbo"
          },
          "version": {
            "type": "string",
            "description": "The version of the AI model.",
            "example": "1.0.0"
          }
        },
        "additionalProperties": false
      }
    }
  }
}

Server-Side API Code Generation (2 Minutes)

Now with a valid OAS file in hand, we can leverage server-side code generators to implement the boilerplate code for this API.

While it’s easy to find a plethora of client-side code generators and SDKs, the number of OpenAPI-based server-side code generators is limited. Blackbird has us covered again.

Using Blackbird’s CLI, we’ll take the AI Chatbot OpenAPI spec and use it as an input to Blackbird’s code generate command:

blackbird code generate -s ./ai-chatbot.json -t go -o ai-chatbot-api

This command generated the whole API project in Go, including schemas for request/responses and handling for each endpoint.

Let’s test it out:

# Run the chatbot API on my localhost
cd ai-chatbot && go run cmd/ai-chatbot/main.go

Great! The API is up and running on localhost. Blackbird stubbed out the three endpoints for this API as well as the schemas. Here’s a quick look at the API’s routes (in routes.go):

func (h *APIHandler) GetRoutes() Routes {
 return Routes{
  {
   "submitChatMessage",
   "/v1/chat/messages",
   "POST",
   h.HandleSubmitChatMessage,
  },{
   "getModel",
   "/v1/model",
   "GET",
   h.HandleGetModel,
  },{
   "setModel",
   "/v1/model",
   "PUT",
   h.HandleSetModel,
  },
 }
}

With the generated endpoint handling and schema code, I can quickly implement one of the operations — I’ll choose /v1/chat/messages:

// This endpoint allows users to send a message to the AI chatbot and receive a response.
// Submit a chat message to the AI chatbot
func (h *APIHandler) SubmitChatMessage(ctx context.Context, reqBody ChatMessage) (Response, error) {

 return NewResponse(200, ChatResponse{Response: "This is a pre-canned chat response"}, "application/json", nil), nil

 // return NewResponse(404, {}, "", responseHeaders), nil

 // return NewResponse(500, {}, "", responseHeaders), nil
}

It’s a rough implementation, but it’s nice to have the schemas already defined where I need them as well as stubs for the error cases (these were pulled directly from the OAS file).

Finally, let’s test this out on localhost with a quick curl command:

# Curl the /chat/messages endpoint
curl --request POST -d '{"message":"Hello chatbot!"}' http://localhost/v1/chat/messages

{
  "response": "This is a pre-canned chat response"
}

Deploying the API (2 Minutes)

The generated API code “works on my machine(tm)”. But the real test is if we can get it containerized, deployed, and tested in a hosted k8s environment. Once again, Blackbird has me covered:

blackbird deployment create ai-chatbot -d ./Dockerfile -c .

With this single command, Blackbird did the following:

Built an image with the auto-generated Dockerfile and my API code
Deployed the image into Blackbird’s hosted k8s environment
Created the necessary mappings to provide a publicly accessible URL for testing

Let’s run our same curl command as before, but this time against the public URL where our deployment is running:

curl --request POST -d '{"message":"Hello chatbot!"}' https://matts-env-5b603.blackbird-relay.a8r.io/ai-chatbot/v1/chat/messages

{
  "response": "This is a pre-canned chat response"
}

Success! In 5 minutes I went from a conversation with AI to working and deployable API code 🚀

If you want to do the same, I invite you to give Blackbird a try. Here are the steps to quickly download the CLI.