Streamline Macrometa API design and testing with Postman

In this blog post, I will outline how Postman helps us build and maintain our tools. We will also discuss how Macrometa uses it to create a better internal and external developer experience. Our platform has various tools like SDKs and CLI that enable developers to utilize the power of a hyper distributed cloud architecture.

Postman is primarily used as an API testing tool, it takes the burden off the developer to create client HTTP requests. That is just one aspect, Postman can also be used for documentation, automated tests, and even aids in the API design phase. We will cover additional options where Postman really shines with its intuitive GUI and sharing capabilities.

Macrometa takes an API-first approach when we roll out new features, so we follow these three steps. The first step is to update our Open API specification, the second step is to update our SDKs, and the third step is to update our documentation. Our goal is to create a seamless and consistent experience for every interaction developers have with the Global Data Network, including related materials.

When we update our Open API specification and deploy a new version of the platform in a test environment the next step would be to support new features in our SDKs. At this point we don’t jump straight to the code, we take a little bit of time to create Postman collections for all new endpoints. After, we do the first initial tests with Postman manually. The goal of that step is to see how the endpoints are designed, what parameters they are using, how the response body works, and how to build a path with parameters. Any response to requests that we get from the API we record in our Postman collection.

Simplify test environments

Since we have multiple test environments with different features, the first thing that makes our life easier is using environmental variables. Instead of having collections with hard-coded URLs, we can just turn them into variables. Let’s walk through an example.

Hard-coded URL:

https://play.macrometa.io/_fabric/_system/_api/function/metadata

Here is an easy way to change test environment:

We only need to create an environment in Postman for this to work.

That leads us to other important environment variables like user access.

Streamline authentication options

Most of the APIs need some kind of authentication, it would be tedious work to add API keys or tokens to each request manually. Postman can save credentials in environments, on the collection level, or a combination of both.

Easily add Edge Functions

Now that the basics are set up we can start to add requests. Recently we added Edge Functions to our platform, so we updated our collections accordingly.

Let’s take a look at one of the endpoints created. Deploying the Query Worker to the Edge Worker endpoint will deploy the Macrometa Query Worker to Akamai Edge. Endpoint has four query parameters, some of them are mandatory and some of them are set to default. The benefit is that we can turn on and off parameters with one click and see the API response.

How would you go about it in code? We would delete method parameters, add new ones, and run the whole code. It depends on the level of abstraction in the SDK but there is always a doubt if my code is working fine or if the request I am sending is wrong. That can be time-consuming if the structure or code has to be redone. If the Postman collection request is working at least I know the request structure is ok and it is time to check the code. I would argue that it is better to prepare everything before we start to code.

The same idea can be applied to the body. We can change it on the fly and quickly test responses.

In addition to that some endpoints have additional credentials, we can set them up as variables so that we don’t accidentally leak confidential information while sharing collections. You can find more on how to be on the safe side in this article Using variables | Postman Learning Center.

Now that collections are set up and working for us, we can run them as many times as we want. Postman offers us the option to save every response as an example.

That is beneficial for many reasons. For example, now I can just copy the response and create methods in our tools (SDKs and CLI) that can parse the response object. No need to run a debugger in the IDE and watch the response variable, and no need for

console.log(response)

We know exactly what we need to get. Postman can save multiple examples, a good practice would be to save unsuccessful requests as well. That way, we can show the developers how to handle error requests.

Now it is just a matter of creating an abstraction of endpoints in the SDK. That should be easy work since we know exactly what and how to code.

Save time with a single source of truth

You can debate after reading this, that this is just a double work, but that is only if you do not consider the added benefit of sharing. It is possible to share collections with your teammates but we went one step further, we are sharing our collections with all the developers using Macrometa.

For developers, it is perhaps easy to read blocks of code used for client requests, but team members are not only developers. Technical writers would benefit directly from Postman collections since they can interact with the platform, check the saved responses, and be confident that they write consistent documentation. The QA team can use Postman collections to build automated tests. When maintained correctly it can be a single source of truth for the whole organization.

We have been using Postman to create the first draft of collections for new features. The GUI that Postman provides helps us to see inconsistencies between various endpoints that support the same feature.

Get started today with Macrometa and Postman

To sum it all up I want to highlight what we are getting with just a little bit of extra effort before we jump into our preferred IDE. Here are five great reasons to implement Postman in your workflow:

1. While building Postman collections, you can learn how the API works
2. You can save request and response parameters and be sure of what we need to implement in SDK code
3. You can share collections with other team members and users of the platform
4. Your team members that have less technical backgrounds can easily work with the API
5. Since Macrometa has recorded various responses, it is a good starting point for documentation (ex. document all error requests)

You can request a 30 day trial, set up credentials in Postman, and test the platform quickly and easily and check out our collections. Let us know how you are using Postman on our Slack channel, we look forward to hearing from you!