DEV Community

Cover image for Testing and documenting your APIs with Vim-Rest-Console

Posted on

Testing and documenting your APIs with Vim-Rest-Console

I have previously written about a few plugins that I enjoy immensely while working with vim every day.
I had so far forgotten an obvious one until I read a post on about yet another VSCode extension copying its behaviour from the already existing and great Vim counterpart!
Not to be a complete troll but it's nice to see that the other editors are finally catching on... 😁
Sadly they are not reusing the existing syntax making sharing those requests among co-workers not using the same IDE not quite possible...

It would be interesting to try unifying those various plugins and get one common syntax. That way, the IDE troll-war wouldn't prevent people from having the niceness of versioning their requests!

Anyway, I thought a quick review of the vim-version could be a nice thing to have on, so without further ado here we go.


In essence, this plugin is quite simple: it defines a .rest file format and provides one command to run the HTTP call under the cursor of a .rest file. By default, this command is mapped to <C-j> but I had hard time remembering it so I remapped it to <C-x> (for eXecute).

For a complete look at the doc, just follow the usual :help rest-console😀. But let's have a look at the basic syntax.

A simple request looks like this:

// here you can put some options: 
// - either cURL options
// - or Http Headers for your request: e.g. content-type, ... 
GET /api/status
Enter fullscreen mode Exit fullscreen mode

As you can guess, there is a way to avoid repeating the host of your request and the headers that you'd like to have by default. You can do that in the global section of your .rest files.

Best use an example to see how that would work:

# Global section
// set the host for the whole file

// set some common header
// those can be overriden for specific calls
Accept: application/json
Content-Type: application/json
// usually most of the api you're gonna call are gonna be secrued behind 
// some authentification scheme. 
// I tend to put mine at the top of the files (of course you need to 
// change those frequently as they have an expiration date)
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.{...}.ka3IfQFX0-Yb5uFp45f97y0zEevNf3en8TLzoPEJDu0

// you can also setup some variables here: 
username = John Doe
password = NOT_a_g00d-password

// the two -- coming next are important: they indicate the end of of the global scope

-- // <-- to start a request block, put two dashes
# Get some resource // be nice and put some comments about what your request does
GET /api/resource

# Create a user
POST /api/users
  "name": username
  "password": password
// note the use of the variables above

Enter fullscreen mode Exit fullscreen mode

⚠️ an important thing to keep in mind

Vim-rest-console does NOT encode your URLs and this is particularly something to keep in mind when your API allows some complex filtering on your GET requests.

I lost a couple of minutes almost an hour on this particular request last week. My API leverage some of sailsjs' powerful ORM to allow to write queries like: ?filter[name]={\"startsWith\":\"jojo\"}. While writing it in my Rest-console file I had completely forgotten about this, hence my request wasn't returning me any match. Once corrected back to: ?filter[name]=%7B%22startsWith%22:%22jojo%22%7D all was good again. 🙏

In short:

As always, vim shows that it's a full-blown IDE for whoever wants to make it their own and I hope that this quick example will help you on your vim-journey. Don't hesitate to reach out if things are unclear!

Top comments (2)

marceloandrade profile image
Marcelo Andrade R.

Really nice plugin, super useful for testing directly in the editor.

leojpod profile image

yes I really like to be able to quickly try stuff and validate what the api will return to me before digging in the Front-end or back-end to back-end interactions