Testing and documenting your APIs with Vim-Rest-Console

Originally posted on dev.to/leojpod as part of my on-going series about vim.

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 Dev.to 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 dev.to, so without further ado here we go.

vim-rest-console

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:

http://someurl:port
// here you can put some options: 
// - either cURL options
// - or Http Headers for your request: e.g. content-type, ... 
GET /api/status

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
http://localhost:1337

// 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

⚠️ 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!