Code Quickstart
In this tutorial, we'll be using the Blackbird CLI to generate code for a Simple API project
Before you get started
This tutorial assumes you have already have the Blackbird CLI installed and have an entry in our API catalog. If not, please download the Blackbird CLI by following the Getting Started guide and follow the API Quickstart Guide. Although not necessary, it is also recommended to have followed the Mocking Quickstart Guide. If you haven't done those already, you should do so now.
Once we have the Blackbird CLI downloaded and an entry in our API catalog we can begin generating project code.
Additionally, generating and editing code involves both file editing and terminal commands and thus it is strongly recommended to open VSCode (or your preferred IDE) if you have not already.
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. Please ensure Docker is running, then run the following command.
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.