I’ve seen a lot of forums posts, emails, and tweets from folks asking what cURL is and how to use it with APIs.
First of all, cURL stands for “client URL,” and is a command line tool for file transfer with a URL syntax. At the most fundamental, cURL is how you talk to a server – how you provide the URL for the location and the data you want to send. It supports several different protocols including HTTP and HTTPS on almost every single platform, making it a great tool for describing how to interact with an API. In fact, it’s the first tab on the Watson API Service documentation and often the first “code” readers see.
Unfortunately, cURL can be a little messy for humans to build and parse. However, there are both UI and commmand-line alternatives. Let’s take a look at a few alternatives, with the Watson Speech to Text List models method API as an example.
This article describes options for a variety of API tools. No preparation is needed.
Take about 5 minutes to read this article and then try out the tools on your own.
HTTPie is a command-line HTTP client that is touted as more friendly to users. It also includes a more expressive, color-coded UI:
You see some differences with the responses, including the addition of some parameters for cURL and the noticeable absence of the full header information.
Using a command-line client comes down to personal preference. If I am just trying to test to see if something works and responds, I can see myself using cURL in this scenario. If I am trying to actively debug something in a response, HTTPie is easier to read and just feels easier to work with.
Postman is a UI-based client for all things related to API development, and it’s arguably one of the most popular. Postman is very powerful. As I mentioned with HTTPie, it really comes down to personal preference for which UI-based tool you like.
Postman gives you a history of all the requests you built and even data-stamps them, which can be nice for collecting data points or references as you work with an API. Think of it as the client taking notes for you.
What gets a little tricky is how to build calls with multiple pieces, such as parameters, headers, and authorization. Consider the following List Models example:
apikey trick, you can provide the endpoint and use the Authorization tab to specify a user name of
"apikey" and a password of your API token. You can see the UI provides the status code, time, size, and body. Tabs at the bottom provide additional information like headers and options for viewing the body with color and JSON formatting.
Advanced REST Client
My first UI-based client was Advanced Rest Client, originally available as a Chrome plug-in. In 2017, it moved from a browser-based plug-in to a native application for Windows, OS X, and Linux.
Just like Postman, Advanced Rest Client saves a history of all requests you made. This history is part of the reason I gravitated towards Advanced Rest Client instead of a terminal experience. It also includes integration with Google Drive if you want to save your requests and responses.
You need to click the Authorization tab with a
apikey user name and a password that is your API token. Make sure the authorization is set to basic, which should be the default. The following screen capture shows what the header looks like, including the authorization hash, which is set automatically based on the information you provide in the Authorization tab.
Advanced Rest Client is my preferred client. However, both Advanced Rest Client and Postman are so similar in basic functionality at this point, and I flip back and forth between the two.
One of my favorite development tricks is just throwing a URL in a browser. Of course, this approach only works for GET methods.
Enter the URL for listing the models. In Chrome, I get a system pop up so I can type
apikey as the user name, and my actual API key as the password:
Depending on your browser, you might have a slightly different layout or experience.
There are many ways you can interact with APIs, either through a terminal or a UI. Picking the right tool for you comes down to the user experience that you are looking for.
No matter what tool you use, cURL and its many wrappers allow you to familiarize yourself with an API before building your application. Seeing a complete response unhindered by an SDK, a bug, or another issue in your code, can help you build a more efficient solution faster.
What is your favorite API tool? Download and try using one or more of these tools to see which one works the best for you.