Code Quickstart

In this tutorial, you'll use the Blackbird CLI to generate code for an API project.

Before you get started

Before you get started:

• Download the CLI. For more information, see Download the CLI and log in.
• Add or create an API. For more information, see Add an API.
• Open your preferred IDE, such as Visual Studio Code.
• (Optional) If you want to use code run or code debug commands, install Docker. For more information, see Get Docker.

1. Generating Code

Now that we have an entry in our API catalog, we can generate code for a Simple API project.

For the purposes of this tutorial we will use the go template. It is important to note that you can reference your own templates as well as customize our go template as it is publicly available to view in our Github Generators Repository.

The command will then prompt you for various variables and module enabling. For the puposes of this tutorial we will use some standard variable names and enable all modules.

At this point, we should expect to see various logs as we generate our project. Once the project is generated, we should see a new file with all the necessary modules and go files for a project.

2. Running and Testing our Code Locally

Now that we have a new Simple API project, we can run the code locally and curl the say-hello endpoint.

Although we are able to curl the endpoint, we should quickly notice that the operation has not been implemented yet.

3. Containerizing our Code

Now that we our project can run locally, the next step would be to fix the unimplemented say-hello endpoint. We can use a combination of the Run and Debug commands in the Blackbird CLI to do this seamlessly.

The first step is to containerize our code, run it locally, and intercept traffic to the API in a hosted environment. The code run command will handle all of the above.

Note: Use the Dockerfile that we generated in step 1 of this guide.

At this point, a Docker container should be spun up and we should be able to test our API code beyond localhost. By running the instance list command, we can check the publicly available URL and once again curl the endpoint. If you had followed the Mocking Quickstart Guide before this tutorial, you may notice that the mocked hostname has been reused for our Code instance.

4. Debugging our Code

Now that we have containerized our Code, we can finally debug and fix the say-hello endpoint using the debug command.

Let's first start by creating a code change to the API. We should first create a new file named schema_message.go under internal/api.

Next, let's edit the GetHello function in operations.go to return the proper message.

Next, we need to set up debugging in our IDE. If you are using VSCode, use the following launch.json file in the .vscode directory.

And now finally, we can run the code debug command.

At this point we should see our API server listening and the go-simple-api server starting up.

Next we should attach a debugger, if you are using VSCode, the VSCode debugger can be found under the Run tab. Once our debugger is attached, we should set a breakpoint somewhere in the code (like in operations.go).

Finally, if we curl the say-hello endpoint now, we should see that the breakpoint is hit.

The code run and code debug commands allow us to develop in a "hybrid" model. Teams can collaborate on code running on a user's machine with the public URL. This mode can also be further used in CI pipelines where a VM may checkout the code and start a code run session.

5. Next Steps

Now that we have debugged the say-hello endpoint and our code works as expected, the final step is to deploy our code in a more "permanent" environment. Please follow the Deployment Quickstart Guide.