Discussion about API clients

This article is a discussion about API clients. Without being a comparison between the best API clients, this article talks about the pros and cons of some popular tools to send HTTP requests to an API. The goal is not to elect the best one, but rather to try to answer the following question: what we should consider when choosing an API client, and what are the challenges when using one?

Some context

I like discussing tooling because as a developer choosing the right tool is often what makes me more productive in my job. I am talking about the "right tool" because I am not necessarily looking for the best one but the most appropriate one for my needs in a given context. The topic of API clients is not new to me, indeed the first post I wrote on this blog in March 2019 (and my most-read article on DEV.to where I re-posted it) was about using the vscode extension "REST Client" instead of Postman. This article is still relevant and in fact, I have been using REST Client as my main API client for a few years on different projects and in different teams.

Yet I am not writing now to convince you to use "REST Client" or any other tool. Besides, you probably already have a favorite tool you are using to send HTTP requests. Indeed, there are many options: Postman, REST Client, Thunder Client, Nightingale, Insomnia, RapidAPI Client, Hoppscotch, and HTTPie just to name a few. There are many reasons why people choose one tool over another:

• it has more features than others
• some colleagues suggested it
• it's the latest tool featured on ProductHunt
• everyone in the company uses this API client
• it would be time-consuming to learn how to use another API Client

I don't think these are good enough reasons, so I will talk to you about what matters to me when using an API Client.

Ease of use

When I am using an API client, it's to make requests to an API and get responses. It's often to test an API or to debug the API I am developing. Therefore what's important to me is to have a simple tool that makes it easy to write HTTP requests, and display the responses and that's it.

All conceivable functionalities vs. essentials features

A lot of tools try to compete with each other by providing more features or very advanced features. First, it's useless because you are not going to use most of them. Second, it's counterproductive because having too many features will make an API client more complicated to use.

One good example is Postman which went from a simple tool that makes HTTP requests to a real white elephant. To be honest, I am quite impressed with all the features you can find in Postman: the company has done an amazing job to build a platform that helps you in each step of your API lifecycle (specifications, design, documentation, testing, monitoring, ...). However, the downside is that Postman became bigger, slower, and less easy to use. I have no doubt Postman brings a lot of value to many developers that are building their APIs, yet a lot of people (like me) don't need all these unnecessary features and would be better with a simpler tool. Postman is just an example, there are many other API clients that overwhelm you with concepts you don't need (workspace, collections, mocks, flows), that require you to sign in and configure a bunch of things before being able to write an HTTP request.

So what are the essentials features an API Client should have besides sending requests to an API and displaying the response?

• First, it should support the "protocol" (REST, SOAP, GraphQL, gRPC) used by the API you want to query (pretty obvious but not all API clients support gRPC or GraphQL for instance).
• Second, it should support environment variables. You will need them to easily switch between environments: sending requests to an API in QA and to the same API in Production for instance. Variables can also be useful to store the result of a previous request and use it in another request.
• Third, it should allow version control of your request (we will come back to this later).

I think that's all you need. In my opinion, testing and integration with CI/CD pipelines (to automate testing) are nice-to-have functionalities but not mandatory. Indeed, if you want to do some complex tests with big scenarios that run in parallel, you are probably not using an API Client for that and rather develop proper integration tests using more appropriate tools.

Integrated tools vs. standalone tools

Some API Clients are standalone software, whether rich clients (like Postman, or Nightingale) or web applications (like Hoppscotch). Some are directly integrated with your developer tools and IDEs. I feel more productive when everything is in one place and I leave my IDE as little as possible, so that's why I prefer an API Client integrated with my IDE. I find it easier to use a familiar UI in a tool I already know and like rather than using a completely different tool. Everyone has his own way of working so you may prefer a standalone tool and that's fine as well. Just take the time to think about what's best for you.

If you are fond of vscode, you have different API clients available as extensions, for instance: REST Client, Thunder Client, and RapidAPI Client for VS Code. If your everyday IDE is Visual Studio, there is an extension REST Client based on the REST Client for vscode. If you only swear by IntelliJ IDEA or Rider, all JetBrains IDEs have a built-in HTTP Client.

GUI tools vs. text-based tools

There are 2 types of tools: GUI tools and text-based tools.

Generally, GUI tools are easier to use than text-based tools because they offer a simple way to create and send an HTTP request. Of course, this is not always the case: I already talked about some API clients that have a complex UI because of their many features. Fortunately, other GUI tools have managed to keep a simple and clean user interface. That is precisely how Thunder Client has been designed: a lightweight API client with an easy-to-use UI; and it's a success. I particularly like the GUI-based tests of Thunder Client that allow you to quickly do basic tests on HTTP responses without scripting anything. Test scenarios will be quite limited, yet you probably don't want to use an API client for more complex scenarios. There are many other API clients with a great UI, take the time to test several, the choice will probably be a matter of personal preference.

Then, why bother with a text-based tool instead? How could it be easier to manually write an HTTP request in a plain text file than using a GUI for that? Because when you use a text-based API client like REST Client you write your request following the standard RFC 2730. It's a standard so you will find it everywhere to describe the requests, including in the documentation of most popular APIs. It's quite straightforward so you won't have a hard time writing the requests.

Moreover, these kinds of API clients (which are often IDEs extensions or built-in in an IDE) will understand the HTTP text files (with .rest or .http extension) and help you write the requests. You can write multiple requests in the same file and don't have to learn how to use a specific tool, just to write requests in plain text. Therefore, once you are used to the raw syntax of HTTP requests, using a text-based tool becomes even easier to use than the simplest GUI tool.

💡 I already mentioned them before but examples of such text-based tools are:

• REST Client in vscode
• REST Client in Visual Studio
• HTTP Client in Rider or any other JetBrains IDE

Collaboration

The reason why most API clients are a no go for me is that they don't facilitate collaboration. Collaboration is an important part of my job so I need an API client that makes it easy to share requests with others.

Are you ready to pay the price for team collaboration?

Although a few API clients totally lack collaboration features, many of them have nice features to collaborate with your team. However, that is also how the companies behind these tools make money: charging for collaboration features. Usually working with an API client is free for individuals but you have to pay when you are a company or a team. You can see for instance the pricing page of Postman or the one from RapidAPI. I have nothing against that: these companies put a lot of work and money into making these great tools, they need to be profitable and make money. Yet the question is: are you (or is your company) willing to pay for an API client?

If the answer is yes, then fine, choose the best tool for your team, buy some licenses and enjoy. If the answer is no, then how do you intend to work with your colleagues without these collaboration features? Let me guess, you have found a way to export your collection of requests to a file. So each time a new colleague joins your team, you send him/her the file by mail; no one has the same version of the file but you don't care. Or maybe you have put it in a shared drive so everyone can edit the requests; you just have to hope that 2 people don't edit it at the same time. Why not put the file on a flash drive and pass it on to each other while you're at it? I think you understood what I was getting at: if you work with a team, pay for collaboration features, or choose a free API client suitable for teamwork.

Version control is the key

In my daily work as a developer, I work in a team and I want to share requests with them, allow them to edit them, and see the history of changes made. It's funny because it's the same kind of thing you want for your application code when developing. And what helps you with that? Version control. So if you use a git repository to version your application code, there is no reason why it would not be a good fit for your collection of HTTP requests.

Besides, that is exactly what some API clients like Thunder Client or Postman offer: integration with external git repositories. Please note that is not necessary for your API client to have a git integration to share your requests through git, as long as your requests are available in a text file you can version it's fine. So why bother with an obscure "cloud synchronization" of your requests when you can share them with your team through a git repository?

💬 The sweet spot when you are building an API is to store your API application code and your requests to call/test this API in the same git repository.

How requests are stored is important

I previously mentioned how some tools like Thunder Client offer a git integration with external git repositories. Requests and environment variables used by Thunder Client are stored in JSON files that you can add to your git repository. In a similar way, with Postman you can export requests and environment variables in JSON files and version them. There is a big problem with this way of doing things: using JSON files to version HTTP requests is not convenient at all! I have no problem with the JSON format itself, as a developer, it's something I often use. However, HTTP requests stored in a JSON file are not easily readable by a human. If you version HTTP requests, it is not to struggle to understand the history of changes or to have a hard time resolving conflicts between changes made by you and other developers of the team.

I have seen some QA people using Postman for integration testing that were exporting their Postman data (collection, environments, ...) and versioning it in a git repository. What started out as a good intention turned out to be a very bad idea:

• the exported collection was just a huge JSON file that contained all the requests and tests, so each change was made to this same file with the inconveniences I mentioned previously
• editing the JSON file directly and especially the tests written in javascript is a nightmare because with the Postman export the code is stored as string in the JSON (forget about using code quality tools 🥲)
• the environment files versioned were containing secrets so secrets were committed in clear text in the git repository 😱

To avoid these caveats, I think the best way to store HTTP requests is to store them in HTTP text files following the standard RFC 2730. I already talked about text-based tools that were following this approach, unfortunately, I did not find any GUI tool that was doing that (probably because GUI tools always have extra features with things that can't be easily stored in an HTTP file).

If you pay for an API client with which your requests are synchronized in the cloud with your colleagues, you probably don't care how the requests are stored. However, I hope your API client knows how to handle merge and conflicts (1 or more requests edited by several colleagues at the same time for example). Even if it does, be aware it can be not that easy to manually resolve these conflicts in a GUI tool.

Final thoughts

Using the right tool for a given context

I think you understood that there was no perfect API client. So once again, the answer to choosing the right one will be "it depends".

If for your project, you need to choose an API client that will only be used by developers of your team that are coding in vscode, maybe REST Client, Thunder Client, or RapidAPI Client for VS Code are interesting choices.

For a lot of reasons I explained previously I am not a big fan of big standalone tools like Postman. Yet, Postman is installed on my laptop, and if people send me their requests collection to test their API, I would be crazy not to take advantage of it and rewrite every request just because I prefer to use other tools.

I like the HTTP request format and I think people using API clients should be familiar with it. Unfortunately, sometimes people that need to use an API client don't have a technical background. In that case, maybe GUI tools with a simple interface are better suited than a text-based tool. Thunder Client with its scriptless testing feature might be a good option (although it requires you to install vscode which is more intended for developers).

There are many API clients that you can use. Without knowing all of them, it can be a good idea to know what are the alternatives to the most famous ones, in order to choose the right one for your current context.

What am I currently using?

As far as I'm concerned, I prefer using HTTP requests in HTTP files that I edit in a text editor or an IDE and that I commit to a git repository. That way, I have several HTTP files with HTTP requests grouped by concern. When I or one of my colleagues make a change to a request, the others just have to do a git pull to get the change. We use something standard and we are not directly dependent on a specific tool because HTTP files are supported by several tools.

I have used REST Client for quite a while now, and I am happy with it: simple but works fine, no need to pay a subscription, it's just a vscode extension to install.

However, as I have started recently to use more and more Rider, I am also using more and more its built-in HTTP Client which is awesome. If you are using Rider or one of the other JetBrains IDEs I recommend you to try the built-in HTTP Client because:

• you don't have to leave your favorite IDE to make HTTP requests to an API
• it supports HTTP requests, gRPC requests, WebSocket requests, GraphQL
• it has many features to help you write the requests like converting cURL requests to the HTTP request format
• it supports environment variables that can be stored in a public environment file (stored in the git repository) or private environment file (local file containing sensitive information that will not be committed to the repository)
• it allows you to write response handler scripts in JavaScript (directly in the HTTP files or in external js files), which opens the door to many possibilities like writing tests

And the icing on the cake, as you see on the tweet below there is a CLI to execute these HTTP files from the command line. It means that if you have written tests for your HTTP requests with the HTTP Client, you can execute them in your CI/CD pipeline. It also means that even without a JetBrains' IDE you can execute HTTP request files.

💡 Even if you are using a private environment file to store secrets environments variables, it's often not very convenient to share it with your news colleagues. I wrote an article on the topic that showed how you can store secrets in Azure Key Vault and script their retrieval and the generation of the secret environment file using Azure CLI.

In summary

I talked about a lot of things but in concrete terms what matters to me when using an API Client is ease of use and collaboration. You may not have exactly the same needs, yet I think these are 2 aspects you should pay attention to when choosing an API Client. As you have read in this article, each API client has its advantages and inconveniences so even if you favor simplicity and collaboration you won't find a perfect tool. So what should you choose? I don't have the answer to that, I think you should try different tools and find what is the most appropriate in your context. But you should definitely not take the first one that comes along just because others use it.