Using cURL to issue API Requests

In the previous post, we looked at Postman, a great tool for exploring API requests and responses. In this post, we’ll discuss another popular tool for issuing API requests: cURL.

What is cURL?

cURL (pronounced “curl”) is a command line tool for transferring data using URL syntax. It’s free, open source software that you can use to issue API requests and receive responses in return. It can do lots of other things too — but since this site is about using APIs, we’ll focus on that aspect of its functionality.

Why cURL?

These days, I rarely use cURL — because I find Postman to be a far superior tool for issuing API requests and examining responses. That being said though — cURL can still come in handy at times. For example, if you’re wanting to create a script that programmatically issues several API requests and writes the responses to a file, cURL may be a good choice for that. Or, maybe you’re one of those devs who prefers a good command line tool over an GUI app like Postman — cURL may be a great fit for you.

Regardless of whether or not you ever actually *use* cURL, it’s important to at least be familiar with it. First and foremost, because API documentation commonly contains examples that show how to issue API requests using cURL. And for newer APIs that don’t yet offer corresponding SDKs in various programming languages, you’ll often find only cURL examples in the API docs. If nothing else, just understanding cURL syntax is important so that you’ll be able to read and understand these examples.

The following screenshot shows a cURL example request in the Smartsheet API docs. The request specifies:

• An API endpoint: https://api.smartsheet.com/2.0/folders/{folderId}
• Two headers: Authorization and Content-Type
• The HTTP verb: PUT
• The request body: '{"name": "New name for folder"}'

Getting started with cURL

Get started with cURL by completing the following steps.

Step 1: Determine if cURL is installed on your machine

If you’re running Windows or Mac OS, your machine likely has cURL installed by default. To determine if cURL is installed on your machine, open a command prompt and enter the following command:

curl --help

If the command is not recognized, cURL is not yet installed on your machine. Proceed to Step 2: Download the curl executable.

If the command results in the display of some limited help content, cURL is already installed on your machine. Proceed to Step 3: Issue your first request with cURL.

Step 2 (if necessary): Download the curl executable

If you’ve determined that cURL is not yet installed on your machine, you’ll need to download the curl executable (curl.exe).

To do so, use the curl Download Wizard (on the official cURL website) to determine which install is right for you, and then download the binary via the Downloads page.

Note: All you really need is the curl.exe file — you don’t need the full package that contains the cURL library and source code.

Tip: If the long list of options on the Downloads page seems too daunting, you might try finding curl.exe via a simple Google search (e.g. “curl.exe download for mac OS“).

Step 3: Issue your first request with cURL

cURL is a tool that runs locally — once it’s present on your machine, you’re ready to issue you’re first API request. To do so, open a command prompt and enter the following command:

curl https://catfact.ninja/fact

This command issues a GET Random Fact request to the Cat Fact API. We don’t have to explicitly specify that the request verb is GET — because it defaults to GET if no verb is specified — and the API doesn’t require any form of authentication. The following screenshot shows the curl command that issues the API request and the response received in return (in JSON format).

Closing thoughts: cURL versus Postman

It’s certainly worthwhile to know what cURL is and to understand its basic syntax for issuing API requests (so that you can comprehend examples in API docs). However, if you’re anything like me, you likely won’t use it very often. Personally, I found Postman to be a much more robust tool for issuing API requests and exploring responses, for a variety of reasons:

• User interface: Postman’s graphical user interface (GUI) makes tasks like specifying API request headers and parameters extremely straightforward. No need to memorize a bunch of command line flags as is the case with cURL.

• Efficiency: The ability to specify variables in Postman that can be used across requests and even throughout multiple Collections in a Workspace is terrific. This means I can specify a variable value once, and if/when it changes, I only need to update it in one place.

• Optimal organization & reuse: The ability to organize requests into Workspaces and Collections in Postman and to save them for future use is invaluable.

• Collaboration: The ability to easily share my Postman Workspaces and Collections with others (and vice versa — to access others’ Workspaces and Collections) is a great collaboration feature.

(This isn’t to say that it’s impossible to achieve at least some of these same benefits with cURL; I just haven’t invested the time to learn how to do so.)

So there you have it…

…a brief look at cURL– a command line tool that you can use to issue API requests. If you’re curious to learn more, the internet is full of curl command examples, and the official cURL website contains in-depth info as well (https://curl.se).

Next up, we’ll take a look at Fiddler, a tool you can use to examine API request and response data exactly as it’s being transmitted over-the-wire. But first — a quick knowledge check: