If you create JSON API, you probably know by heart the support for tools such as Postman, Insomnia, Curl. However, when querying with them, it is not possible to store API tests in a repository and manage them with version control. I also thought it was impossible until I found this video. JetBrains tools have a built-in ingenious plugin - HttpClient. In this post, I have prepared for you a short demonstration of its capabilities using Ruby Mine and Ruby on Rails. API tests in the repository? Can be! Very much!
As a demonstration environment I will use a simple application written in Ruby on Rails. It took me 7 minutes to create this simple API with simulated authorization! I was timing myself on purpose. That's why I love RoR! But to the point.
The application has a simple structure. The main actor is the user who can own books and cars. Collector. Let's say it's such a typical directory application. Simply put.
I created the data structure with the following migrations.
Model definition:
And controllers.
Routing:
And ApplicationController, into which I put practically all the logic.
In API we can:
- Check if the application is running (
homeaction). - Download all books of a given user from the database.
- Download all cars of a given user from the database.
- Download a list of all users in the database.
- Log in to the application and obtain an authorization token
Access to specific user data is secured with a token that should be provided in the Authorization header.
Before starting, I created a few users, a few books and a few cars in the database.
We start our adventure with HttpClient. Just create a file with the .http extension and RubyMine will do the rest and adjust the interface to fire queries.
I have created the api_test.http file.
First requests. I check if the API works. One line is enough:
GET http://localhost:3000
And the result:
Okay, but it probably won't end with one request. Fortunately, I don't have to enter the address in subsequent queries every time, what's more, I can have addresses configured for different environments and run my client in one of them.
I add the http-client.env.json file in which I set the environment and the url variable.
{
"development": {
"url": "http://localhost:3000"
}
}
And now I can use a variable instead of a patched url. The IDE tells me everything beautifully.
We separate subsequent queries with three hashes: ###
It's time to log in
I am adding a new request, this time of the POST type. See how easy it is to define headers and parameters.
Authorization was successful and I got an auth_token in response. Now it's time to capture it, assign it to a variable, and use it in subsequent queries. This is done in the code that we put in braces with the percentage {%%}, which is just JavaScript.
POST{{url}}/login
Accept: application/json
Content-Type: application/json
{
"email": "user1@email.com",
"password": "password"
}
> {%
auth_token = response.body['auth_token']
client.global.set("token", auth_token)
%}
###
GEThttp://{{url}}/users/1
Accept: application/json
Content-Type: application/json
Authorization: Bearer {{token}}
We can now authorize our inquiries with a token:
HttpClient also has something for test fans. You can write automated tests for your queries! These tests are run together with queries, and their results are visible in the IDE runner.
###
GEThttp://{{url}}/users/1
Accept: application/json
Content-Type: application/json
Authorization: Bearer {{token}}
> {%
client.test("Get User",function() {
client.assert(response.body['books_count'] === 5, "Books count returned is wrong")
})
client.test("Status",function() {
client.assert(response.status === 200, "Response status is not 200")
})
%}
What now? Git commit, git push. And we have versioned tests of our API.
You can find the repository with the above code here.
Top comments (6)
For VSCode users, there's a similar extension: Rest Client
Cool! I've tested it. It would be great if it would be compatible with JetBrains HttpClient. I see that the json structure is a bit different so in order to use it as a specs in repo whole team should use the same editor I guess. Do you have any experience with this approach?
Of the companies I've worked for, generally the team all use the same IDE (PHPStorm, VSCode, Atom etc.).
Makes it much easier to share config files, debug issues.
You are lucky, I've never been working in the company when all developers have the same IDE 😅
Nice write up, the first set of images are cool, how did you create them?
Here carbon.now.sh/