Testing and documenting your APIs with Vim-Rest-Console
Tags: vim, http, tutorial, productivity
Published: 2020-02-27 16:45:53

---
title: Testing and documenting your APIs with Vim-Rest-Console
published: true
description: who need a postman or a postwoman when vim brings you the whole post office?
tags: vim, HTTP, tutorial, productivity
cover_image: https://dev-to-uploads.s3.amazonaws.com/i/n4v8fri4cyj7u8h4n7kc.png
series: Vim Reviews
---

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](https://dev.to/monisnap/bye-bye-postman-let-s-share-your-rest-api-calls-in-team-easily-h6l) 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... 
{% post monisnap/bye-bye-postman-let-s-share-your-rest-api-calls-in-team-easily-h6l %}

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](https://github.com/diepm/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 <kbd>\<C-j\></kbd> but I had hard time remembering it so I remapped it to <kbd>\<C-x\> </kbd> (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](https://github.com/diepm/vim-rest-console#52-global-definitions) 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 <del>minutes</del> *almost an hour* on this particular request last week. My API leverage some of [sailsjs](http://sailsjs.com/)' 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!