Understand curl more
Almost every API shows how to interact with the API using curl. So before moving on, let’s pause a bit and learn more about curl.
- Why curl?
- Try using curl to GET a web page
- Requests and responses include headers too
- Unpacking the weather API curl request
- Query strings and parameters
- Common curl commands related to REST
- Example curl command
- Quiz yourself
Why curl?
One of the advantages of REST APIs is that you can use almost any programming language to call the endpoint. The endpoint is simply a resource located on a web server at a specific path.
Each programming language has a different way of making web calls. Rather than exhausting your energies trying to show how to make web calls in Java, Python, C++, JavaScript, Ruby, and so on, you can just show the call using curl.
curl provides a generic, language-agnostic way to demonstrate HTTP requests and responses. Users can see the format of the request, including any headers and other parameters. Your users can translate this into the specific format for the language they’re using.
Try using curl to GET a web page
As mentioned earlier, one reason REST APIs are so familiar is that REST follows the same model as the web (see What is a REST API?). When you type an http
address into a browser address bar, you’re telling the browser to make an HTTP request to a resource on a server. The server returns a response, and your browser converts the response to a more visual display. But you can also see the raw code.
To see an example of how curl retrieves a web resource, open a terminal and type the following:
curl http://example.com
Curl will retrieve the HTML code for the site example.com. The browser’s job is to make that code visually readable. curl shows you what you’re actually retrieving.
Requests and responses include headers too
When you type an address into a website, you see only the body of the response. But actually, there’s more going on behind the scenes. When you make the request, you’re sending a request header that contains information about the request. The response also contains a response header.
-
To see the response header in a curl request, include
-i
in the curl request:curl http://example.com -i
The header will be included above the body in the response:
~/projects $ curl http://example.com -I HTTP/1.1 200 OK Content-Encoding: gzip Accept-Ranges: bytes Cache-Control: max-age=604800 Content-Type: text/html; charset=UTF-8 Date: Tue, 04 Dec 2018 04:35:43 GMT Etag: "1541025663+gzip" Expires: Tue, 11 Dec 2018 04:35:43 GMT Last-Modified: Fri, 09 Aug 2013 23:54:35 GMT Server: ECS (sjc/4F91) X-Cache: HIT Content-Length: 606
-
To limit the response to just the header, use
-I
:curl http://example.com -I
The header contains the metadata about the response. All of this information is transferred to the browser when you make a request to a URL in your browser (for example, when you surf to a web page online), but the browser doesn’t show you this information. You can see the header information using the Chrome Developer Tools console by looking on the Network tab.
-
Now let’s specify the method. The GET method (read) is implied by default when no other method is specified, but we’ll make it explicit here with the
-X
parameter:curl -X GET http://example.com -I
When you go to a website, you submit the request using the GET HTTP method. There are other HTTP methods you can use when interacting with REST APIs. Here are the common methods used when working with REST endpoints:
HTTP Method Description POST Create a resource GET Read a resource PUT Update a resource DELETE Delete a resource GET is used by default with curl requests. If you use curl to make HTTP requests other than GET, you need to specify the HTTP method.
Unpacking the weather API curl request
Let’s look more closely at the request you submitted for the weather in the previous topic (Make a curl call):
curl -X GET -H "Cache-Control: no-cache" -H "Postman-Token: 930d08d6-7b2a-6ea2-0725-27324755c684" "https://api.openweathermap.org/data/2.5/weather?zip=95050&appid=APIKEY&units=imperial"
(In the above code, replace APIKEY
with your actual API key.)
curl has shorthand names for the various options that you include with your request.
Here’s what the commands mean:
-
-X GET
. The-X
signifies the method used for the request. Common options areGET
,POST
,DELETE
,PUT
. (You might also see--get
used instead. Most curl commands have a couple of different representations.-X GET
can also be written as--get
.) -
-H
. Submits a custom header. Include an additional-H
for each header key-value pair you’re submitting.
Query strings and parameters
The zip code (zip
), app ID (appid
), and units (units
) parameters were passed to the endpoint using “query strings.” The ?
appended to the URL indicates the start of the query string. The query string parameters are the parameters that appear after the ?
:
?zip=95050&appid=APIKEY&units=imperial
(In the above code, replace APIKEY
with your actual API key.)
After the query string, each parameter is separated from other parameters by the ampersand &
symbol. The order of the query string parameters doesn’t matter. The order only matters if the parameters are on the left of the query string (and thus part of the URL itself). Any configurable parts of the endpoint that appear before the query string are called path parameters (we’ll dive into these later).
Common curl commands related to REST
curl has a lot of possible commands, but the following are the most common when working with REST APIs.
curl command | Description | Example |
---|---|---|
-i or --include |
Includes the response headers in the response. | curl -i http://www.example.com |
-d or --data
|
Includes data to post to the URL. The data needs to be url encoded. Data can also be passed in the request body. |
curl -d "data-to-post" http://www.example.com |
-H or --header
|
Submits the request header to the resource. Headers are common with REST API requests because the authorization is usually included in the header. |
curl -H "key:12345" http://www.example.com |
-X POST |
Specifies the HTTP method to use with the request (in this example, POST ). If you use -d in the request, curl automatically specifies a POST method. With GET requests, including the HTTP method is optional, because GET is the default method used. |
curl -X POST -d "resource-to-update" http://www.example.com |
@filename |
Loads content from a file. | curl -X POST -d @mypet.json http://www.example.com |
See the curl documentation for a comprehensive list of curl commands you can use.
Example curl command
Here’s an example curl request that combines some of these commands:
curl -i -H "Accept: application/json" -X POST -d "{status:MIA}" http://personsreport.com/status/person123
The request could also be formatted with line breaks to make it more readable:
curl -i \
-H "Accept: application/json" \
-X POST \
-d "{status:MIA}" \
http://personsreport.com/status/person123 \
(Line breaks are problematic on Windows, so I don’t recommend formatting curl requests like this.)
The Accept
header tells the server that the only format we will accept in the response is JSON.
Quiz yourself
Quiz yourself to see how much you remember. What do the following parameters mean?
-i
-H
-X POST
-d
When you use curl, the Terminal and iTerm on the Mac provide a much easier experience than using the command prompt in Windows. If you’re going to get serious about API documentation, but you’re still on a PC, consider switching. There are a lot of utilities that you install through a terminal that just work on a Mac. Also, if you’re in Silicon Valley, using a PC instead of a Mac might make you look old-fashioned (see Why do most startups purchase MacBooks for their employees?). Alternatively, you can run Linux on Windows, and you’ll get the same terminal experience (Bash shell). See this example tutorial on how to install Bash on Windows.”
About Tom Johnson
I'm an API technical writer based in the Seattle area. On this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, AI, information architecture, content strategy, writing processes, plain language, tech comm careers, and more. Check out my API documentation course if you're looking for more info about documenting APIs. Or see my posts on AI and AI course section for more on the latest in AI and tech comm.
If you're a technical writer and want to keep on top of the latest trends in the tech comm, be sure to subscribe to email updates below. You can also learn more about me or contact me. Finally, note that the opinions I express on my blog are my own points of view, not that of my employer.
19/165 pages complete. Only 146 more pages to go.