As you explore API documentation, you can’t help but bump into curl examples. For the uninitiated, these may look unfriendly and confusing. REST assured (that’s an API joke), it’s not as bad as it looks. Knowing the basics of curl will help you interact with APIs.
One of the reasons that curl is intimidating is because it can be used a lot of different ways. It works with a bunch of data transfer protocols, but for APIs you’ll usually see it use HTTPS and HTTP. That’s the same way that web browsers exchange data. See, this isn’t so foreign after all.
Install curl (You May Already Have It)
You’ll find curl pre-installed on modern Mac OS. Windows 10 and others may also already have curl, depending on how your computer setup. A quick way to check is to open a command line prompt (also called your Terminal):
curl -h
Or on windows:
curl.exe -h
On success, you’ll see a long list of command options. Almost every letter of the alphabet, capital and lowercase, are mapped to commands in curl. That’s one of the things that makes it seem difficult.
If you see an error like:
command not found: curl
That means you’ll need to install curl. You’ll need to download a binary for your operating system. Make double sure you choose a binary option, because getting the source would require you to compile curl on your own system—that’s way more complicated than most people need.
Try the example curl command again with the -h (the help option) to make sure you’re good to go.
Your First curl GET Request
It may seem like hyperbole, but your first curl request is going to space. Well, almost. We’ll be calling the Open Notify API to get the number of astronauts currently outside our atmosphere (likely on the International Space Station).
Try this:
curl http://api.open-notify.org/astros.json
After a short time to make the connection, you should receive a result like this:
{"people": [{"name": "Oleg Kononenko", "craft": "ISS"},
{"name": "David Saint-Jacques", "craft": "ISS"}, {"name":
"Anne McClain", "craft": "ISS"}], "number": 3, "message":
"success”}
Don’t worry if that blob of text looks confusing. That’s JavaScript Object Notation (JSON) and is a lightweight way to communicate data structures. Many APIs use JSON responses.
It can be easier to read on multiple lines with the structure shown through indentations:
{
people: [
{
name: "Oleg Kononenko",
craft: "ISS"
},
{
name: "David Saint-Jacques",
craft: "ISS"
},
{
name: "Anne McClain",
craft: "ISS"
}
],
number: 3,
message: "success"
}
The number of astronauts in space in this case is three, but your result could be different, because Open Notify is always up-to-date. It also provides additional information on the people in space and where they are.
This simple example uses a curl GET request with no authentication (that is, Open Notify doesn’t require you to identify yourself with an API Key or similar token). As for curl, it assumes a GET request, but you can also explicitly state it with the following command:
curl -X GET http://api.open-notify.org/astros.json
GET is an HTTP method used to read data. These simple API calls don’t even require curl—you could load this data directly in your browser.
For more advanced API requests, you’ll start to see the value of curl, so let’s move on to writing data using a POST request.
Can curl POST JSON?
You can use curl to read and write all kinds of data. That’s what it does! You can use JSON, XML, URL encoded data, and more. When using APIs, new data is often written with a POST request. If you’ve ever filled out a form on a website, that data is also sent with the HTTP POST method.
For this POST example, we’ll turn to Stripe, the online payments API. Copy the curl command from its documentation for creating a charge. It will look something like this:
curl https://api.stripe.com/v1/charges \
-u sk_test_1aB23CdEfgHIjklmN4opq5rs: \
-d amount=2000 \
-d currency=usd \
-d source=tok_mastercard \
-d description="Charge for jenny.rosen@example.com"
It’s important to copy from Stripe, because they will give you a test token that works. When writing data you almost certainly will need to authenticate, because otherwise anyone could write data anywhere, including in your account. Stripe gets around this to provide a great developer experience by generating test tokens in their documentation—even if you haven’t signed up.
The token is passed with curl’s -u flag, which takes a username and password. In this case, the token is the username and the password (which would be on the other side of the :) is blank.
When you perform the operation, you’ll get back a big blob of JSON. Success! But, even though JSON was in the response, we haven’t quite POSTed JSON yet.
What is -d?
One of curl’s many flags is -d, which sends data along with our request. Because curl can be used in so many different ways, this flag is versatile. It can be used once or multiple times (as Stripe does here). By default, curl will send all -d data bunched together with & separating them. It URL encodes the data as would happen with a form (x-www-form-urlencoded).
In the case of Stripe, this is exactly what they’re looking for! Other APIs may be looking for JSON directly in the body of the data that you POST.
How to POST JSON with curl
You’ll need to do things a little differently to use JSON as part of your API request. Here’s how a hypothetical API call might look with JSON in the data:
curl https://example.com/api/places \
-u 1aB23CdEfgHIjklmN4opq5rs: \
-H "Content-Type: application/json" \
-d '{"name": "Just Bob", "type": "Coffee"}'
In this example (which uses example.com and isn’t live), you’d write a new coffee shop to a place API. The name and place type are sent along in JSON with the -d flag. Note that the entire JSON is wrapped in single quotes, which allows us to use double quotes in the JSON without things getting really ugly.
There’s also some authentication (with the -u flag) and then we also need to tell the server that we’re sending JSON. To do that, we add a new Header with the -H flag.
Take APIs Beyond curl
Now that you’ve made your first GET and POST API requests, take your skills further. Use Twilio, Slack, and (more) Stripe to make and combine API calls. With Hands on APIs for the Casual Coder you’ll get five short and fun lessons to master how APIs work.
Questions About curl?
You’re now familiar with the basics of curl, but might have some questions. I’ve gathered common and anticipated questions below, but feel free to reach out with your own and I’ll try to answer them.
Is curl Always Lowercase?
When you run it from the command line, it’s always lowercase: curl. Additionally, that’s how the creator refers to it and how most others write it, as well. Sometimes it’s given a capital c: Curl.
The only time it’s consistently written with any uppercase letters is for the PHP library, cURL.
What is the difference between wget and curl?
You may already be familiar with another command line utility, wget, which has some similar functionality to curl. The focus of wget is centered on HTTP, HTTPS, and FTP. That means wget is perfectly capable of doing everything shown above.
However, wget only supports basic authentication (username and password), so you might have difficulty accessing APIs with more advanced methods.
What is cURL PHP?
The cURL library in PHP can be used to make API and other calls from your PHP code.
There is more curl than simply the command line utility. The curl command we used above is built on a C library called libcurl. PHP’s cURL is also based on libcurl.
What is cURL in WordPress?
If you’ve dove into WordPress source code, you may have seen cURL mentioned. As WordPress is built on PHP, it uses the cURL library to make its own requests. As of WordPress 2.7, there are helper functions like wp_remote_request you can use instead of calling cURL directly.
