There are several ways of testing your awesome API and the most popular one is using Postman. The downside of Postman is that you can’t save your tests (or requests) to the API with your project. Another way is to create unit tests, but unit tests are meant for code testing and not integration testing. Plus, an API needs external sources like a database. And then there are HTTP files, which are the solution for me. In this article, I’ll show you how you can test an API by using HTTP Files in VSCode.
Table Of Contents
Goals Of Using HTTP Files
After reading this article you
- Know what HTTP files are and what they can do
- Write your own HTTP files to test an API
- Know how to use variables inside the HTTP files
- Create and change environments so you don’t have to change variables
The Idea Of Using HTTP Files In Short
The idea behind these HTTP files is that you can execute requests to an API, or any online application. This way you can check if the desired response is given with specific requests. You can send GET, PUT, DELETE, and POST requests, with all the same options and settings as with Postman.
When you execute an HTTP file the editor will provide the response and UI. This can be an error, JSON, image, or HTML, depending on the API you are testing.
One big advantage is that you can store the HTTP files in a location of the project/API, which is stored in Git for example. This allows you to have the HTTP files every time you clone your project without having to install another program and hope it has saved all the previous requests (Postman).
The API
I will be using a straightforward API to demonstrate the HTTP files. You can download the example API below.
This API is a minimal MVC REST API, made with C# and .NET 7. This API has a few mappings representing standard endpoints, like GET, POST, and DELETE.
There is no database, class libraries, or unit tests. It’s just a very basic but working API. You can download, build, and run it.
Visual Studio VS VSCode
To create and execute HTTP files I will not use Visual Studio, but Visual Studio Code, or VSCode for short. Although Visual Studio does support using HTTP files, a lot of functionality is missing. VSCode has an extension called REST Client, which has more functionality and options.
The support of HTTP files in Visual Studio is based on that VSCode extension, but I guess it’s not completely done… Yet. Although I use Visual Studio HTTP files, I prefer the VSCode extension.
Installing REST Client
We need to install the extension before we can start using HTTP Files. So let’s open VSCode and head to the extensions tab. Search for “Rest client”.
All you need to do is hit that “Install” button on the lower right corner of the extension. This won’t take long.
That was the easy part. Let’s make a request!
Making Requests By Using HTTP Files
Making requests by using HTTP files is just like coding. You create a file, with the extension http, and start typing all the information you need to make the request. I will show you examples of the GET, DELETE, and POST. I think you can figure out the PUT yourself.
For the next subchapters, I highly recommend running the API and keeping that API running.
Create An HTTP File
First, open the folder of the API in VSCode. Inside is another MovieAPI, but don’t load this folder, load the parent. Next, create a folder called HttpFiles. Now it should look a bit like this:
As I said, the HTTP files are just filed with the extension http. Let’s create a new file inside the folder HttpFiles and call it GetMovies.http. We can place all the requests and tests we need to get the movies inside this file.
GET Request
If you open the GetMovies.http you will notice it’s just a blank file. Let’s change that. Write the following code inside the GetMovies.http:
localhost:7248/movies
Notice the Send Request appears above it.
Note that the 7248 in the URL is the port on my machine. Maybe your machine uses a different port.
If you press the Send Request, the REST Client will send a GET request to the API and place the result on the screen. Go ahead, press it.
Now you can see what the API is sending back when you do a simple GET request.
A Second GET Request
The API has a second GET request mapping. The /movies/{title}. With this mapping, you can request movies with a specific title or movies that contain parts of the given title. I can think of multiple requests for this one.
Since this is also a GET, and good for the demonstration, I want to create the GET with the title in the same file as the previous GET. But if we add another request this happens:
Do you see the Send Request? REST Client has no idea which request to send. That doesn’t mean you can have multiple requests in one file. We need to separate them.
Simple use a comment style to separate the different requests:
### GET All the movies localhost:7248/movies ### GET all the movies by title 'shrek' localhost:7248/movies/Shrek
This will tell the REST Client you have different requests and you can execute them separately.
Let’s add another one, just for the fun of it:
### GET All the movies localhost:7248/movies ### GET all the movies by title 'shrek' localhost:7248/movies/Shrek ### GET movie that does not exist localhost:7248/movies/BLA
Variables
In the previous example, I have 3 URLs with a domain (localhost) and a port (7248). But what if that changes? What if I want to test the same API that is stored online? It would be a bit stupid to change all the URLs each time I want to change the domain.
To fix this we can use variables. These are just like programming-language variables: You declare them, give them a value, and use them by placing them in the URL with curly brackets like {{name}} (no @ char!). Easy.
You declare a variable with an @ char, like @name = value. There is no need for a semicolon or something. If I want to store the URL localhost:7248 in a variable, the file would look like this:
@baseUrl = localhost:7248
### GET All the movies
{{baseUrl}}/movies
### GET all the movies by title 'shrek'
{{baseUrl}}/movies/Shrek
### GET movie that does not exist
{{baseUrl}}/movies/BLA
If the base URL would change I only have to change it once. You can also put the movies endpoint in a variable, but chances are slim that might change too.
POST Request
The example API contains a POST endpoint, where I have tried to simulate a login procedure. If the login is correct, the API will send back a token and a refresh token. To get these two tokens you want to make a POST request with the correct username and password in the body of that request.
Let’s create a new HTTP file and call it Users.http. Inside this new file, I declare the baseUrl again, with the localhost:7248. But putting the URL to the {{baseUrl}}/users/Token would not work, because that would be a GET request and we need a POST request. The solution is easy: Put POST in front of the URL.
It also needs a body, with the username and password. This is, just like in Postman, a JSON-formatted string. Below is an example.
@baseUrl = localhost:7248
### Do a login
POST {{baseUrl}}/users/Token
{
"UserName": "admin",
"Password": "12345"
}
If you send this request you will get an error:
Expected a supported JSON media type but got “”
Interesting. Since the request doesn’t know how to handle it, we should set the Content-Type. The API expects a JSON body by default.
We can set all kinds of headers inside the request, like the Content-Type. Just place them under the URL and above the body:
@baseUrl = localhost:7248
### Do a login
POST {{baseUrl}}/users/Token
Content-Type: application/json
{
"UserName": "admin",
"Password": "12345"
}
And that will give the following result:
Updating information, or the PUT request, is pretty much the same, except you replace the POST with PUT.
Storing Response Information
In the case of the login, where you get a token, you want to store that information and reuse it for another request. This will save you time by not having to copy-paste the token. Let’s demonstrate this with the result Users/{Token} in the API.
The first thing you need to do is name the request with the @name. Then execute the request for receiving the token. Then you retrieve the information from the request by its name and use it. Below is an example.
@baseUrl = localhost:7248
# @name login
POST {{baseUrl}}/users/Token
Content-Type: application/json
{
"UserName": "admin",
"Password": "12345"
}
###
@token = {{login.response.body.token}}
GET {{baseUrl}}/users/{{token}}
In the example above the request for the token retrieval is named login. After it’s executed the response will be saved in the memory. In the second result, the variable @token is declared and filled with the value of the login request.
You can use the variable @token also in other requests. You don’t have to extract the value from the login request again. Even after you have used it in a request.
DELETE Request
Alright, last request demonstration. Let’s delete stuff.
Well, actually… It’s pretty simple. All you have to do is have the right URL, the parameters, and the DELETE request method. Let’s go back to the movies.http and add the following request:
### DELETE movie
DELETE {{baseUrl}}/movies/Shrek
That’s it! Shortest chapter ever!
Environments
Although you have all the information you need to work with REST Client and HTTP files, I want to spend a short chapter on environments. Well, I am not known for being short.
Environments help with setting the value of certain variables. If you have a development and a production environment you want to switch easily and quickly between both environments without changing important variables. The REST Client extension supports this with a JSON file.
Maybe you already get the idea, but environments are super strong when you want to test different environments with different settings. I have one API for example, that is located in a staging area (Azure Cloud), on a production host, and a local variant. I have over 20 HTTP files and by simply changing the environment I can switch from Cloud to production or local.
Settings.Json
The first thing you will have to do is create a new file. You should know this file needs to be in the folder .vscode. A folder dedicated to settings. Within this folder, create a new file with the name settings.json.
Because it is a JSON file, we start with the curly brackets and a new section called rest-client.environmentVariables. If done right, this new section immediately gets a section called $shared.
{
"rest-client.environmentVariables": {
"$shared": {
}
}
}
Shared Variables
Variables are key-value pairs and should be in the shared section. Then you specify the same keys with other values in the different environments. If an environment does not have a specific variable, the value of the variable in the shared section will be used.
Let’s start with the baseUrl variable, which we have used in the previous HTTP files. Declare the variable in the settings.json like this:
{
"rest-client.environmentVariables": {
"$shared": {
"baseUrl": "localhost:7248"
}
}
}
Now remove all the declarations (not the usage!) of the baseUrl variable in the HTTP files. Make sure the API is running and test a few requests, they will still work.
Other Environments
Now we are going to add two environments: local and production. We do this by adding new sections to the rest-client.environmentVariables. Like this:
{
"rest-client.environmentVariables": {
"$shared": {
"baseUrl": "localhost:7248"
},
"local": {
},
"production": {
}
}
}
The local environment doesn’t need to change the baseUrl, so let’s not add the baseUrl to this environment. The production won’t be localhost:7248, so if you want to use the production environment you will need to use a different URL. For demo purposes, let’s say https://awesome.api.com.
{
"rest-client.environmentVariables": {
"$shared": {
"baseUrl": "localhost:7248"
},
"local": {
},
"production": {
"baseUrl": "https://awesome.api.com"
}
}
}
Switching Environment
Executing a request will result in a request to the localhost:7248. How to change the production environment? Simply press CTRL + ALT + E.
You see all your declared environments and you can select the one you want to use. If you select the local environment, the localhost:7248 will be used. If you select the production, the https://awesome.api.com will be used.
Let’s select the production and run a request. An error in the lower right corner of the VSCode appears.
The getaddrinfo should be a hint, but I can tell you it can’t find the URL awesome.api.com. Also not the label production in the lower right corner. This way you know in what environment you are currently working.
Conclusion On Test An API By Using HTTP Files In VSCode
HTTP files are very convenient when you create or work with an API. It’s pretty easy to test an endpoint and investigate the response. If you keep a good record of your endpoints and create HTTP files accordingly, you will find that it’s also easy to check if a certain endpoint still does what it needs to do.
Although Visual Studio supports HTTP files too, it lacks the environments and the collecting of the responses (November 2023), as I showed you with the fake login endpoint. If Visual Studio is ever going to support HTTP files like the REST Client extension in VSCode, I will certainly move to Visual Studio.
