Creating a basic HTTP client using Vim, cURL and JQ

Arjun Aravind • 20 August 2023 • 6 min read Anyone who's worked with me closely enough knows that when I'm on the computer, I tend to avoid using the mouse as much as possible. It's just a habit that I've developed over the last few years ever since I started getting wrist pains from using the mouse too much.

I follow this to the extent that, these days, I browse the internet, watch YouTube, use Teams, write code, ~~torrent movies~~ watch Netflix, all largely mouse-free.

Calling and testing APIs, however, has been a thorn in my side for too long a time.

Mainstream API tools (like Postman and Insomnia) don't seem to be for me as there are just way too many shortcuts to remember, plus the options for manipulating responses are limited.

cURL + JQ is a particularly good combo though! The disadvantage with this method is that it's cumbersome to save and view the resultant response. It's also not possible to save the cURL request itself.

And that's when it hit me!

I like using Vim. I like using cURL and JQ. Why not just use them all together?

Yes, I know, there's already a ton of HTTP plugins out there for Vim. But I felt like making my own and, if you'd like to have the same setup, you can recreate this without any plugins or installations. Let's check it out!

Setting it up in 5 minutes

What the flow looks like when it's all setup

Open up your

.vimrc

and paste the following key mappings in it.

cmap <C-E> t.-1
    \ \| '<,'>s/<<\([a-zA-Z_]*\)>>/\=get(http_client_environment,submatch(1))/g
    \ \| echo "Query generated!" <Enter>
cmap <C-X> w !bash <Enter>

Save the file and enter the following command:

:source /path/to/.vimrc

Open three files (
```
env.txt
```
,
```
request.txt
```
and
```
response.txt
```
) in three different windows like in the GIF above.
Paste the text in this link in
```
env.txt
```
and the text in this link in
```
request.txt
```
. Save both the files and enter the following command:
```
:source /path/to/env.txt
```
.
In
```
request.txt
```
, visually select the entirety of the first cURL command and enter command mode (press
```
:
```
). You should see
```
'<,'>
```
appear. Now enter
```
Ctrl + E
```
.

A cURL query with the substituted variables should appear.
And now, for the final act, visually select the entirety of the generated cURL query and press
```
:
```
, again following which
```
'<,'>
```
should appear. Now enter
```
Ctrl + X
```
.

Assuming it all went right, Vim should ask you if you want to "load" a file. We want this so press
```
<L>
```
.
Open the
```
response.txt
```
file and you should have your response!

Tip 1: Try doing the same for the second cURL query as well.
Tip 2: If you have any questions, try looking at the GIF to see what the workflow looks like.
Note 1: If you're having issues, check out the "Troubleshooting" section below.

Quick Explanation and Usage

Hopefully, the process is a bit self-evident but I'll give a brief explanation anyway.

The

env.txt

contains a dictionary that stores all the necessary environment variables. Using the same format shown in the example, you can add a variable of your choice.

In

request.txt

, you can refer to a variable by enclosing the variable in double angular brackets like this:

<<var_name>>

The dictionary should always be called
```
http_client_environment
```
.
The variable names should only contain alphanumeric and underscore characters.
Everytime you make a change to
```
env.txt
```
, you will need to reload the changes by entering
```
:source /path/to/env.txt
```
.

When you visually select a query with variables in

request.txt

and press

Ctrl + E

, a valid cURL query with the substituted variables is generated.

When you visually select this generated query and then press

Ctrl + X

, Vim executes the cURL query in a bash shell. That's it, just a bash shell. No fancy stuff.

You might have noticed that the cURL output is being redirected to the

response.txt

file. You don't have to do this but, this way, you may find that you can inspect both the request and response in Vim itself.

Finally, JQ is a really helpful CLI tool for processing JSON output. Using JQ, it's possible to format, parse and process JSON. In the sample

request.txt

file, you can see that we parse the response and extract only the fields that we want using JQ.

Learning JQ is outside the scope of this article but I would really recommend just skimming through all the functionality that it provides.
Once you know what's possible with it, you can always refer the docs to see how to implement them whenever needed.

Troubleshooting

If you run into any errors, go over these points to make sure you're following the process correctly.

Ensure that you stick to the
```
"key": "value"
```
format when adding an environment variable. Remember to add a comma at the end of every dictionary line.
If any changes are made to
```
env.txt
```
, always enter
```
:source /path/to/env.txt
```
to load the changes.
After adding the
```
Ctrl + E
```
and
```
Ctrl + X
```
key mappings to your
```
.vimrc
```
, make sure you've loaded the changes by entering
```
:source /path/to/.vimrc
```
. You only have to do this the first time.
When visually selecting a query but before pressing either
```
Ctrl + E
```
or
```
X
```
, ensure you enter command mode (by pressing
```
:
```
) and the
```
'<,'>
```
appears.
If the response isn't showing in the file you've redirected the cURL output too, make sure that the filepath specified in
```
request.txt
```
is that of the correct file.

How it works

Vim is the gift that just keeps on giving! While getting this setup to know, I was very surprised to learn of some of the capabilities that Vim provides.

For the environment variables, we make use of Vimscript. It's a small scripting language that can be used to extend Vim's capabilities. You can do all sorts of things from using variables to defining functions. Vim even provides a standard library with a set of helpful functions!

The dictionary in
```
env.txt
```
is a Vimscript dictionary that allows us to store key-value pairs.

The key mapping that we're using to generate the cURL queries is just a simple matter of finding a variable in the visually selected range and replacing it with the value from the dictionary.

You might have heard of Ranges in Vim which let you specify a text ranges to perform various operations on. Similarly, the
```
'<,'>
```
that we see is a range too!
To be more precise, it is the range which is used to refer to all the characters that have been visually selected in the editor.

As mentioned before, the second key mapping that we're using to run the cURL + JQ query basically just executes the query in a bash shell.

---------------------

Hopefully, this article was interesting to read. Let me know if you did actually go ahead and use this setup. Contact me if you have any criticisms or improvements. Cheers!

Creating a basic HTTP client using Vim, cURL and JQ

More from this blog...