I enjoy writing API's. I think it is fascinating how we have a somewhat universal platform of letting computers talk with each other. That said, over the years, APIs have become better and better at giving end-users the ability to input and output records. When I first left college, web services was going to be the greatest thing ever. You had with many of these services, a universal data contract, known as SOAP, that could be used to easily access and pull in the API's contents. After web services, WCF services became more widespread. I come primarily from a Microsoft environment, so the upgrade from web services to WCF was fairly easy since Visual Studio had a lot of the items baked in. But as that was going on, Rest and JSON-based services became more and more widespread. And while I played with these services, I never really dove in unless I was consuming one.
That said, being in the Microsoft world, I always thought of API calls as simple client-based calls you'd have to write some special one-off code for. Typically, I'd have a simple .net web client code that I would have in a base or helper class call the JSON service, and have either a custom data contract or wrapper, consume and parse the object to the data I needed. Having my experience in WCF and web services, I really felt that calling Rest services was almost going backward in time. VS made it easy to just plop in a WSDL, and it would do the heavy lifting of generating my client, objects, and code I needed.
So, during a brief time off due to Covid in 2020, I decided to migrate some code and logic I wrote years ago into Rest-based services. It started with a chatbot. I wanted to migrate the UI to a web-based solution and found Rivescript to be an easy platform to migrate my old AIML solution over to. That said, it did come with a large headache. Every time you'd call the page, the client would have to download a 2 meg file from the internet, onto their device. I worked with caching on the client-side, but all in all, I did not find this to be a great solution. So, after some playing around, I settled on building a Node.js server that the UI could call. This now meant I had a Full-stack application, as now I had a proper backend to manage. As I am fairly new(ish) to the ecosystem of hosting and writing rest servers, I decided that if the client was calling my box, and didn't pass params, I should give notice on how to properly call my API. I've seen other APIs do this in the past, so I modeled it around their "UI".
I thought to myself, this is perfect. I am giving users a proper way to call my API if they want to play with it on their own. And as I learned from other APIs I modeled after, it does work. That said, I really wasn't happy with it. You see, I see other sites that have APIs. I see these really nice interfaces that give you the ability to test out your own code. It's something I wanted but didn't want to have to hand code. Then after a presentation on Swagger, I saw recently, I found out that I was behind on what I really knew.
Swagger was introduced to the world back in 2011. It was picked up by SmartBear and the Linux foundation picked it up as a standard in 2015. By 2017, the biggest competitor to Swagger jumped ship to the Swagger standard by having a tool that could convert RAML to Swagger docs. All of this occurring, and I completely oblivious to it. So, recently I decided to upgrade my API. As the API is ultra lightweight, and running on a Raspberry Pi, I decided to have a hard-coded Swagger JSON document instead of auto-generating a document on the fly. after a bit of trial and error on the Swagger Editor I hand wrote a YAML file that seemed to work perfectly with my API. Since my project is in Node.JS, I decided to use Swagger UI Express as my default look and feel.
I did experiment with Redoc-Express however, I was not a fan of it. See, Swagger offered me something I was seeing on other sites that I thought was absolutely brilliant, an easy way to execute the API right from the website itself. After some playing around, I found some interesting things I needed to do in order to get my item working. For starters, I decided it would be easiest to leave the URL structure alone, and if you hit my base URL site, you are redirected to a subdirectory URL that hosts the Swagger express platform. I was initially trying to run it off the base, however, I was running into small issues here and there, and settled on a sub-hosted URL instead. I also wasn't a fan of the giant Swagger UI logo on the top of the page. That said, I did find some forums that showed you could inject CSS attributes to the page, and after 5 minutes on the google, I removed much of the extra bloat that was on the site.
The Swagger doc also provided me a few more things that the traditional "URL" I had spun up did not give me. I was now able to show that my code was an MIT license. As well, since others could use the API, I decided to spin up a terms and conditions doc as well. I am a developer, not a lawyer! I do not want others to use my chatbot to catfish poor souls on dating sites or be used in a way other than what it was intended. That being, a small rough draft of a simple chatbot hosted on some developers' personal portfolio and hosted on a free Heroku account as well as on some Raspberry Pi out in the cloud somewhere. So, after 20 minutes of googling, I have a basic Terms page as well.
So, after all this extra effort, I think the outcome of it is a lot better than its original variation. 
My new page has links on the top, as well as the descriptive text of what the API is. From that point on down, there is a description of what the params do, as well as the ability to actually make calls to the API, and see the results of the API. The interface to me at least is 100x better than a simple API response object telling the user that you called it wrong, and I learned a lot throughout the process.
If you want to try it yourself, the website is https://bot.liukonen.dev or the original UI to the bot can be found at https://chat.liukonen.dev. Please let me know what you think of it, as well as any suggestions, recommendations, or thoughts.
Top comments (0)