Simplifying API development:

Interacting with your APIs through the command line using Zum

Stop writing scripts to interact with your APIs. Call them as CLIs instead.

During your API’s development cycle, you will probably find yourself calling your API a lot to manually test changes that you make to your code. As you probably already know, this gets really repetitive, really fast. Also, depending on what you use to interact your API, this may include tiresome command line calls that involve multiple lines on each call (if you use tools like cURL), maintaining extra pieces of code (if you write your own scripts to interact with your API) or putting quite a lot of time on describing your API thoroughly (if you use something like OpenAPI and then using SwaggerUI to handle the API interactions). The idea behind Zum is to provide the best of all worlds for you to spend less time/effort on your API interactions and more time/effort on your API development. Let’s see how it works!

(You can read more about Zum on the documentation page or on the GitHub repository)

Quick comparison with cURL

Just to hype this up, let’s see a small comparison between a request to a local endpoint using cURL and Zum.

Let’s say that you have an API that lets you create a song nested inside an album (with id 8). Each song has a name and a duration in seconds. This endpoint is also protected by a JSON web token authorization. With cURL, you would have to write something like this:

curl --header "Content-Type: application/json" \
    --header "Authorization: Bearer super-secret-token" \
    --request POST \
    --data '{"name": "Con Altura", duration: 161}' \
    http://localhost:8000/albums/8/songs

Notice that you will have to manually compose the whole request each time. It would be nice to be able to call something like:

zum <endpoint> <album-id> <auth> <song-name> <song-duration>

Then, you could just run

zum create-song 8 "Bearer super-secret-token" "Con Altura" 161

Seems nice, right? Let’s see how to do it!

Using Zum

To use Zum to interact with your API, there are only two steps:

1. Describe your API using the TOML markup language with with only a few lines
2. Start using the zum CLI.

How to describe an endpoint

To describe your API endpoint, you need to create a zum.toml file. On this file, you will describe the API. To describe the API used as example above (an API with only one endpoint), the content of the zum.toml file should be:

[metadata]
server = "http://localhost:8000"
[endpoints.create-song]
route = "/albums/{id}/songs"
method = "post"
params = ["id"]
headers = ["Authorization"]
body = [
    "name",
    { name = "duration", type = "integer" }
]

This file contains a few configurations, and you can read all about them on the documentation page. Nothing too complicated, but for the sake of this demo, I will not dive in right now. Now that the zum.toml is completed, you can start calling your API!

How to call your API

Now that your configurations are completed, you will need to call your API using an endpoint’s name. Notice that the endpoint got described under a header [endpoints.create-song]. Each endpoint should get created under a header [endpoints.{endpoint-name}], and then can be called using the command zum {endpoint-name}. Also, it is important to notice that the zum command will receive the params first, the headers after that and finally the body. In pythonic terms, what zum does is that it kind of unpacks the three arrays consecutively, something like this:

arguments = [*params, *headers, *body]
zum(arguments)

On our example, the zum command would be called like this:

zum <endpoint> <p:id> <h:Authorization> <b:name> <b:duration>

Where p: means a parameter, h: means a header and b: means a body attribute. Now, a real world call would look like this:

zum create-song 8 "Bearer super-secret-token" "Con Altura" 161

And that’s it! Now you can interact with your fantastic API in seconds! Zum has a ton of nice features, so go check it out!