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 in order 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 one that is really handy 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 a 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:
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 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 its 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 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 much functionalities as Postman but for the usage I have it is quite enough.
What I really 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 to 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 😃
Top comments (17)
Although I liked the tool for easily writing requests against the server, I should disagree with the fact that it does testing, you just perform a request and get a response from the server.
Is there any way to actually do non-manual testing with it, short of generating the code snippet for it and pasting it inside a test?
Yes you are right. I was not talking about automated testing or something like that. I was only talking to manually test your API. I use it mainly for hitting a breakpoint in my API and debug my code.
I am not aware of a way of doing automated testing with that but if you found something I would be glad to hear about it.
How do you add a parameter in the url?
Do you mean like that ? Or something else ?
I mean if you're working on a crud operations and you need to pass a parameter
In my example you can just change the value of the planetName variable. You can also do not use local variable and set environment variable in your vs code settings (rest-client.environmentVariables)
Just came across your article and it was really helpful. But I still don't understand how to pass parameters in POST request
I have written an example in a response to a comment above.
You can do something like the following. Here I am defining a variable @test with a value of HELLO and using this parameter in my POST request.
@test is your parameter, you just have to change its value to pass a different value in your request.
I have been using REST Client for a long time and never knew that we can use variables and we can also pass values from previous results. Thanks for sharing.
As I understood this is only for VS Code what about alternative in Visual Studio ?
I don't know an alternative for Visual Studio but I would say you don't really need to. You can do your usual development in Visual Studio and have VS code opened to do other things like querying your API.
There is one alternative for Visual Studio now called Rest Client (for Visual Studio). It's an extension as well
Insomnia also allows for assigning variables for each environment, really helps with having to update a whole set of requests or when an auth token is required.
The one thing postman does that is nice is the auto generation of documentation, but if you're using .net back end you can do that too with swagger UI.
Can the variables be used inside POST data? I have added an item in a request. I can get the id from the response. Then I want to use the id in a different POST request. It doesn't seem to work:-(
Yes you can, you just have to call the first request, then the second request.
You can find below an example. I tested it, it works fine.
1) Is there anyway I can hit the multiple endpoints
2) Is there anyway to put some assertions
1) What do you mean by multiple endpoints ? You can use variables to change the environment / url you are targetting.
2) I don't know about that but I don't think so.