Testing your API with REST Client

Let's talk about tooling and testing an API!

GUI Tools and their limits

Like most developers I guess, I often use GUI tools like Fiddler or Postman to query an API. Once you get used to the HMI of Postman with all its tabs, it's quite easy to create GET / POST / PUT / ... requests, save them in a collection, and visualize the answers. Postman offers a lot of other features, but a very handy one is the possibility to use environment variables in your requests.

Seems to be the perfect tool you would say. Well, that's true if you want to quickly test an API on your own, and to be honest I use it a lot for that. But when you are collaborating on a real project with other developers, there might be some things you will miss. For me, it's a way to edit, version, and share requests with other developers.

Okay, I know that Postman paid plan allows you to share requests with other people of your team. And I am aware of the collection export feature on the free plan, but that's not enough. I don't really like to be too tied to a proprietary software and its GUI to do things. As a developer what I want is to be able to edit my requests in simple text files that I can put in version control. And here's come REST Client.

What is REST Client?

The REST Client extension is an open source vs code extension developed by Huachao Mao. If I quote the README of its GitHub repository: REST Client allows you to send HTTP request and view the response in Visual Studio Code directly. Let's see that with a simple GET request to The Start Wars API:

05578273

Nothing new or complicated here, just the request you would have written intuitively. Like this, you can write any kind of request you want simply following the standard RFC 2616. Even if you don't know the standard, it's pretty straightforward and you often find samples with this format on the documentation of the API you are querying, like on the Microsoft Graph API documentation for instance.

REST Client works on text files in vscode by selecting HTTP as the Language Mode (by default this language mode is associated with files having the .rest or .http extension). It provides you with some autocompletion and a few snippets to help you write your queries. You can write multiple requests on the same file in vscode just by separating them with ###. Above each request an actionable Send Request link allows you to run the request and see the response in a response panel.

Using variables in REST Client

As you can see below, it is possible to use variables with REST Client. A variable planetName is defined in the file and reused in 2 requests. A variable is also used to name the request GET https://swapi.co/api/people/?search=Luke and makes it possible to use elements from the response (that you can see on the right). Here we are using the homeworld property of the response to retrieve the planet from which Luke was from in the following GET request. With the help of variables you can easily combine and chain requests for the scenario you need to realize.

REST Client allows you to define environments and their associated variables in the user settings file of vscode. For instance, let's say I want to query the Microsoft Graph API (both the V1 version and the beta version of the API), I will add the following JSON to my settings file:

"rest-client.environmentVariables": {
    "$shared": {
        "host": "https://graph.microsoft.com/",
    },
    "graphV1": {
        "version": "v1.0",
    },
    "graphBeta": {
        "version": "beta"
    },
}

I have defined 2 environments graphV1 and graphBeta with a specific value for the version variable. These environments share the host as a common variable which is contained in the shared environment $shared. From my request file, I can now switch between environments and use the variables version and host to request the Microsoft Graph API.

What I like about REST Client?

REST Client is a nice alternative to Postman as it allows to easily write requests and query APIs from Visual Studio Code. I am already a vscode user so I appreciate staying in the same environment I know and like for testing an API. REST Client may not offer as many functionalities as Postman but for the usage I have, it is quite enough.

What I like about this tool is that you treat your requests as code: you can commit the files containing your requests, keep track of their modifications and share the requests with your colleagues in your Git project repository.

I have seen quite a few people using it recently in video tutorials and if you have a look at the number of downloads it seems I am not the only one to find it useful.

Getting started

There are a lot of other features in REST Client that I didn't talk about (generate code snippet, request history ...) so don't hesitate to give it a try. You can use it on any API you like (there is even basic support for SOAP) the same way you would use Postman or other tools.

If you quickly want to convert some of your Postman queries, there is a Code button in Postman that allows you to see the HTTP request code that you can just copy and paste in vscode to use it with REST Client.

Or if you prefer you can get started by testing the Star Wars API, you will find below the requests I used. Enjoy :)

#### List of start wars planets
GET https://swapi.co/api/planets/ HTTP/1.1

### Get Luke Skywalker
# @name lukeRequest
GET https://swapi.co/api/people/?search=Luke HTTP/1.1

### Get Luke Skywalker home planet
GET {{lukeRequest.response.body.results[0].homeworld}} HTTP/1.1

### List available resources
GET https://swapi.co/api/ HTTP/1.1

### Search planet with a specific name 
@planetName = Naboo
GET https://swapi.co/api/planets/?search={{planetName}} HTTP/1.1

### Search planet with a specific name in wookie encoding
GET https://swapi.co/api/planets/?search={{planetName}}&format=wookiee HTTP/1.1

### List starships
GET https://swapi.co/api/starships HTTP/1.1