My Project: To create a Microservice based Demo Application
I’m in charge of solution engineering for two of our products here at Ambassador and I set off to create a microservices application a few months ago because I wanted to build something from scratch that I could use to demo our fleet of products (Telepresence and Edge Stack). I envisioned creating something that was approachable to our prospects but clearly showed the value in a real-world business use case. I landed on creating a simple banking app to demonstrate security, authentication, and rate limiting could easily be applied (with Edge Stack API Gateway). Also, as I rolled out new features, they could be tested before going through the commit process (with Telepresence).
I created an API spec with the basic routes I thought I would need and got to work. The first issue I encountered dealt with my backend API. I had created all of the paths off my API spec, but I realized that I hadn't fully fleshed out the paths. I needed to add additional sub-paths for features I intended to implement in the initial release.
My API quickly grew unwieldy, and while it accomplished the initial functionalities, my file was a gigantic mess to look at. My functions, handlers, operations, routes were all located in the same file. I was completely locked in while I built my API, which was great, but afterwards I had to spend an embarrassing amount of time refactoring my massive api.go file into more manageable bite sized pieces.
After my backend was refactored and connected to a fairly simple postgres database, I started to work on the frontend. I personally don’t have a lot of experience (read: almost zero) in building frontend applications, but I did some research and decided to use Expo. I just wanted to get something up and running for my initial release and figured I could change it later if it grew into something else.
I slowly trudged through learning what I needed to React Native to get it up and running to run headfirst into my second issue. The way I had configured my backend API didn’t exactly work with the way that I needed my frontend to work. Some of this is my fault as I added a feature or two that I thought would be really cool, but a lot of it was that I had designed my backend for what my frontend would need but not how it would use it.
I eventually got all of the features in my frontend to work with the backend after jumping back and forth about a billion times. Each time changing one thing and praying that it didn’t have any unintended consequences (which of course it did, welcome to programming). My mission was accomplished, though, and after taking about three times longer than I expected, it was finally ready to demo. It worked well, but it was definitely not the easiest or quickest process I could’ve taken.
So why am I making this blog?
What I Should’ve Done Instead: Enter Blackbird
It was about halfway through my project that I heard rumblings about Blackbird being ready for beta testing (our new APi development tool). I knew that we were creating it, but since I had been responsible for our other products, I hadn't paid much attention to it. As soon as I finished my demo application, I requested access to see what it was about.
I honestly wish I had looked at it while I was creating my demo, because it would have saved me countless hours.
If you recall, the two issues that I mentioned were centered around two things. The first one being that I had created an API spec before-hand, and I unsurprisingly had to expound on the details when building the actual API. This meant that my API spec no longer matched what I had built, and from that point on it was a ping pong match between my frontend and my backend.
The second issue was that even though I had fleshed out my backend, there were things I didn’t know how to handle until I encountered them on the frontend, which only made the ping pong match more intense.
So How Did Blackbird Help?
Blackbird kept me honest. It enables parallel development, advanced mocking capabilities, instantaneous feature testing/debugging, and, as a cherry on top, a persistent deployment that is completely self contained.
Blackbird lets you either bring your own API spec or generate one using AI. Using that spec it will instantly spin up a mock server with a public URL allowing you to constantly validate your api spec with what you have built either on the frontend or backend. I say it ‘keeps you honest’ because it acts as the official starting point (by generating the scaffold code based off of your spec) and finish line while keeping those really cool features at bay.
Project Organization & Time Saved
Remember how I said my original backend API was functional but really messy? When Blackbird generates the scaffolding, it generates an entire project folder on your local machine that's already organized. Now it did take me a second to get familiar with the project file structure, but after I did it was an unbelievable time save. It was already set up for a production level application, it had written the boilerplate code for my handlers, routes, services, helpers, basically everything I needed except the business logic and database connection.
Run Code Locally
Now, let's say I am building out my frontend application using my persistent mock that's been deployed by Blackbird and I want to test the business logic that I have created in my backend. Blackbird lets you run the backend code on your local machine (using some black magic, fairy dust, or the seventh infinity stone Marvel didn’t tell us about) to intercept the mock server and temporarily replace it with your real code. This allows you to actually verify that your application is working as intended, not just with the mock. This blew me away.
I don’t love the idea of working solely with a mock to design the two halves to my application in silos (even if they are united by a spec), but now I am actually able to connect my entire application and have it be publicly accessible without standing up, literally, anything. We can also attach a debugger to our code to set breakpoints and suss out issues.
Not only can I run the code temporarily, but I can also have a steady-state business logic enabled deployment whenever I want. Blackbird will take your code and turn it into a deployment that's persistently available (read: you can turn your machine off and your teammates can still access it). So if I am working in parallel with a frontend developer, I can release improvements to my backend, deploy it, and they can use the new code to continue developing the frontend.
With Blackbird, my process becomes a whole lot simpler. I have to input the business logic for my API, build the frontend (which I can constantly validate to spec that actually matches my code), run my code from my local machine to test it against my frontend, and deploy it for a more permanent environment.
What Else Can You Do in Blackbird?
Modularity
While using Blackbird, I realized a few things. First, Blackbird is modular. The path that I mentioned before is the path that I used, but it's not the only path. You don’t need a mock to create a deployment, you can pass whatever image you want and create a publicly accessible url that's running that image. You can also already have API code, and use the ai spec generator to generate the spec.
Mock Away
Second, I realized that Blackbird can be used as a very advanced mocking tool. When Blackbird generates the scaffold code, the only thing it's missing is the business logic. If you were to build out the code and use canned data, you could have a production-like mock. At first, that didn’t sound very useful, but then I thought back to my experience at another startup. We built a tool that allowed companies to build out their API spec, and generate documentation based on that spec. We had a fairly simple mock ability that would allow you to hit an endpoint in the documentation, but it was creating a separate url for each endpoint, it wasn’t persistent, and there was no logic in any of it.
Using Blackbird, you could theoretically deploy a persistent mock for your Partner APIs, or even Internal APIs to be used for development. This would provide production-like responses while not having to worry about any real data concerns. It would also shift the burden of standing up an environment, and decrease overall traffic for testing.
Finally– Blackbird is not even released yet! What they created in such a short time is actually incredible. There is so much value to unpack with just the basic feature set that's already been rolled out. I can only imagine what other use cases will be discovered as Blackbird is fully built out and generally available on October 1, 2024.
Who Is It For?
Blackbird is for anyone and everyone looking to develop APIs. I see Blackbird as the entrypoint for students to learn how to build a web application. I see Blackbird as a low-cost way for an individual developer to get an idea of the ground, or expand an existing application. I see Blackbird as a way for large organizations to have an API catalog with processes in place to enable their developers to build efficiently and successfully while lowering the costs associated with ephemeral environments and infrastructure upkeep.
Blackbird is versatile, approachable, and powerful. You get out of it what you put into it and since you can use any of the features independent of the others, the use cases throughout the endpoint lifecycle are numerous
Looking Forward- What I’d Like to See Next
There are so many ideas I have for Blackbird, and features I would LOVE to see added in the future, and endless possible use cases. I truly think that it will change the way we develop APIs both at an individual developer level as well as at an efficiency-driven organization.
More Discovery
I mentioned it previously, but Blackbird can act as an API catalog for large organizations. It can be the home for all API specs, and current development. In the future, I would love to see the ability to automatically discover APIs by crawling through a git repository (or multiple). Keeping the specs up to date and notifying developers when changes have been made would be very useful in my opinion.
Spec Iteration
APIs are always changing. Pretty much as soon as we finish the first version, we are planning for the next release. I would love to see the ability to iterate on an API specification, while keeping/maintaining versions, version history, and statuses of said versions. I know this is in the roadmap eventually, and I foresee Blackbird being the central location for companies to monitor their development while also seeing what APIs are currently available, deprecated, or in development.
Less Siloed Deployments
Currently deployments are siloed. In my application, my backend talks to a postgres database that's running in a remote environment. That means that I can’t actually keep my backend in the deployment and use it as the application permanently. Obviously, Blackbird isn’t meant to be a space like Heroku, but I would love to be able to configure my backend to be able to send out requests to my database just as a last check to verify it’s working properly.
Exporting the Code
The last stage of Blackbird, in my mind, should be exporting the code to absorb it into my own infrastructure. Currently there is no easy way to do this. You would basically have to take the project folder and morph it into whatever type of deployment your infrastructure is currently running and go from there. This is something that I know is on the way according to the product team, and with Blackbird still being in early access is understandable.
Feedback
Anyways, I’d love your thoughts as you try out the tool. And if you have suggestions on other things you think would be beneficial to add to Blackbird, I’d be happy to pass that along to the team’s that are working on it.
Top comments (2)
Thanks @rgrantom for that great article. I think this tool is very helpful for large projects and large teams.
Me too, I have been struggling with the need for the mocked versions of my backend APIs to have a mutual agreement with the front end people on what is the API routes and the expected output from this APIs to allow parallel development and can also finish and demo my ideas without waiting the backend people to finish.
I personally would recommend using a simpler tool for just the API mocking part with a good user friendly. I personally developed it to streamline my needs for a simple API mocking tool and I would definitely recommend giving it a try mock-api.net/home It is completely free forever for the first 50 APIs and suitable for the demo purposes.
Love that you're using blackbird!!