Software as a Story: API

TLDR

In this edition of Software as a Story, we’ll be looking at a SaaS tool used for building and testing APIs.

Introduction

Welcome to the 1st edition of Software as a Story! I’m Nathaniel at Mage, and today, we’ll be taking a look at SaaS (Software as a Service) tools out there that help us ship quality software.

Background

I’ve been a software engineer working in full-stack development for about 2 years, and have experienced how APIs are crucial when developing any shared software. When first developing, you start off with either the frontend or backend. The frontend contains our web application or client processing user interaction. While the backend has databases, schemas, or servers to store your data. Once you’ve built them, an inexperienced developer may try to link them directly. This is extremely dangerous as secrets such as credentials could be leaked, and telling anyone who uses “inspect element” where you store your software, along with any credentials used to access it.

API

An API, or Application Programming Interface, is a fancy word for the middle man that will handle fetching from the database using queries, and handling requests from the frontend. There’s also an added layer of security that you may add called API keys to verify that the request came from the client that owns the data, and battle tested APIs help split the traffic between multiple client server connections to speed up response times.

curl command

The first way to access an API is through curl requests, these follow the HTTP Protocol, which is a standard that helps developers design APIs. First let’s take a look at this sample curl command used to fetch real-time predictions for a ranking ML model.

Find the correlation between a cabin on the Titanic and the passenger’s odds of survival.

The command is broken down into 3 important parts. The request, header, and body. As you can see typing this into a console is not very friendly. It’s long and a single mistake means you need to start over. This is where more modern tools come in.

Postman

Postman has a simple easy to use UI that lets you save, store, and share your endpoints for collaboration. Starting with the request, Postman knows all the HTTP methods, so you can select it from a dropdown, then type in your endpoint url.

API Request

We want to send a POST request to https://api.mage.ai/v1/predict

When using curl you have to manually add each header to the response, this is another pain point, but Postman is modern so it automatically sends commonly used headers. If you don’t want these you can toggle them.

Postman lets you configure exactly what you want and don’t want to send.

Finally, we get to the body section located next to the headers tab. To match our “data” parameter, we’ll want to have “raw” selected using the radio buttons, then paste our body. Since our content-type was application/json, we’ll also need to specify that by choosing JSON as the raw datatype.

Choose the data type that matches your data

API Response

Once we’re done, we click the send button and get a monster of a response back. On Postman, we can save this response as a file or as another example or tab.

Notice that the response took 7 seconds, this is often really bad as our goal is 2.5 seconds per request so we can hover over it and look at a breakdown of why.

The 8 second response is far too long.

From these events, we can see that the DNS Lookup took up the most time, a whopping 6.28 seconds. This is often because the subdomain of app.mage.ai requires multiple lookups and redirects. Seeing a breakdown of events helps identify bottlenecks early and the ability to save it in a collection for our backend developers to replicate and test.

API Testing

Another cool feature Postman has is caching. Since everything is cached, there are no extra DNS Lookups and security checks, meaning that subsequent calls will be faster. This is great for when you’re writing tests to verify the output and server response.

Caching means faster testing

Postman has a testing suite programmed using JavaScript with guides to self-learn the library’s commands and functions. Here, I’ll show off one of the most basic tests, the HTTP status, but for more information on testing check the reference manual. Most of the time, you want to make sure your server returns a 2XX response, so we’ll create a script to test for it.

Running the request again shows, under the test results tab, that it passed the test.

Finally, once you have a ton of tests you can export the collection and integrate them in your CI/CD pipeline to automatically run the tests every time changes to the code are made. This helps you keep the code clean and find what you may have broken.

You know that song? (Source: 99 little bugs in the code)

Mentions

Before we end, I’d like to give some honorable mentions, as Postman is not the only viable tool for APIs. Another SaaS tool for APIs that is used at Mage is Insomnia. It functions similarly to Postman where you can create requests and collaborate with a team. In the end, I chose Postman because it was more inclusive with its testing features, documentation, and guides. If you liked this edition of Software as a Story (SaaStory), comment down below about what you’d like to see next! We’re looking for content creators with a developer background and stories to tell! Join us by visiting our Discord or careers page.

Enter the portal