The Simplest Guide to Curl for REST API Requests

If I had to give a one sentence definition of a curl, I would write something like this:

cURL (Client for URLs) is a command line tool that is used for transferring data over the internet via multiple protocols

Short, but powerful! ✨

Let's face it - it's hard to imagine a API world without curl today. Almost every API documentation out there shows you how-to examples using curl.

curl provides a generic, language-agnostic way to demonstrate HTTP requests and responses.

It's handy command line tool that makes it easy to send HTTP/HTTPS requests, receive data in different formats, and even automate these requests through scripting. Whether you're new to programming or more experience user earning how to use curl can save you a ton of time and effort when working with REST APIs.

So, grab a cup of coffee, and let's dive into the basics of curl! ☕

Table of Contents

• GET request
• POST request
• PUT request
• PATCH request
• DELETE request
• Read request data from file
• Write response to file

For demo purposes I'm using {REST-API} - free fake API for testing & educational projects.

📌 Notice for Windows users:
Windows 11: curl is provided with your system.

• If you have Windows 10 version below 1803 (May 2018), install curl from official website (32-/64-bit)
• OR if you already use Git for Windows (downloaded Git from git-scm.com), you have curl.exe under: C:\Program Files\Git\mingw64\bin\. Simply add the path to system PATH and restart command line.

Now, we can open terminal or command line and let's our tutorial begin! ✨

GET request

GET requests are the easiest to send. All you need to do is pass our URL as an argument to the curl command

curl https://api.restful-api.dev/objects

and receive response:

[
   {
      "id": "1",
      "name": "Google Pixel 6 Pro",
      "data": {
         "color": "Cloudy White",
         "capacity": "128 GB"
      }
   },
   {
      "id": "2",
      "name": "Apple iPhone 12 Mini, 256GB, Blue",
      "data": null
   } ...
]

You can use curl with -v (shortcut to --verbose) to switch on verbose mode and see more details of request.

curl -v https://api.restful-api.dev/objects

Let's try url with path params. We want to get object with id 1

curl https://api.restful-api.dev/objects/1/

Url with query params. Fetch item by id:

https://api.restful-api.dev/objects?id=3

Let's try with live example - fetch dev.to articles by author's username.

curl https://dev.to/api/articles?username=ritaly

Multiple query params

When using multiple query parameters in a GET request, we separate them with an ampersand (&).

Take a look into dev.to API - combine 3 query params:

• tag: articles that contain #devjournal
• top: most popular articles in the last 5 days
• per_page: limit to 5 articles per page

📌 Note
Here we had to add double quotes for URL. Without the quotes, the shell might mistake the ampersand for the end of the command.

curl  "https://dev.to/api/articles?tag=devjournal&top=5&per_page=5"

POST request

Create new object with body like this:

{
   "name": "Apple MacBook Pro 16",
   "data": {
      "year": 2019,
      "price": 2049.99,
      "CPU model": "Intel Core i9",
      "Hard disk size": "1 TB",
      "color": "silver"
   }
}

Send POST request with curl:

curl -X POST https://api.restful-api.dev/objects \
-H 'Content-Type: application/json' \
-d '{"name":"Apple MacBook Pro 16","data":{"year":2019,"price":2049.99,"CPU model":"Intel Core i9","Hard disk size":"1 TB","color":"silver"}}' 

In response you see created object (keep its id for later example).

curl options:

• -X <METHOD> - specifies the HTTP method e.g. POST, PUT, PATCH, DELETE
• -H - submits a custom header ( curl uses application/x-www-form-urlencoded as the default Content-Type, we change it to JSON)
• -d - request data also called API payload, as we mention in Content-Type, data is going to be JSON

When you need pass more than one header, just use multiple -X commands.

Like in this sample GET /objects example:

curl -v \
     -H 'Connection: keep-alive' \
     -H 'Accept: text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8' \
     -H 'Accept-Language: en-GB,en-US;q=0.8,en;q=0.6' \
     https://api.restful-api.dev/objects

With -v verbose you can inspect headers applied:

> GET /objects HTTP/2
> Host: api.restful-api.dev
> user-agent: curl/7.79.1
> connection: keep-alive
> accept: text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8
> accept-language: en-GB,en-US;q=0.8,en;q=0.6

Add -A (--user-agent) to change user agent

curl -v \
     -H 'Connection: keep-alive' \
     -H 'Accept: text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8' \
     -H 'Accept-Language: en-GB,en-US;q=0.8,en;q=0.6' \
-A 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/109.0.0.0 Safari/537.36' \
     https://api.restful-api.dev/objects

result:

> GET /objects HTTP/2
> Host: api.restful-api.dev
> user-agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/109.0.0.0 Safari/537.36
> connection: keep-alive
> accept: text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8
> accept-language: en-GB,en-US;q=0.8,en;q=0.6

PUT request

Method to update all fields = replace existing record, thats why we need to provide its id.

Send PUT request (replace with your :id) .

 curl -X PUT https://api.restful-api.dev/objects/:id \
     -H 'Content-Type: application/json' \
     -d '{"name":"Apple MacBook Pro 16","data":{"year":2022,"price":2399.99,"CPU model":"M1","Hard disk size":"1 TB","color":"space grey"}}'

PATCH request

This method is also use to update record, but PATCH only updates specified fields.

Send PATCH request (replace with your :id) .

curl -X PATCH https://api.restful-api.dev/objects/:id \
     -H 'Content-Type: application/json' \
     -d '{"name":"Fruity name"}'

Check your record:

curl https://api.restful-api.dev/objects/:id

DELETE request

Remove our resource with DELETE. No payload required, just again our resource id.

curl -X DELETE https://api.restful-api.dev/objects/:id

Your object has been deleted ;)

Read request data from file

We can read the contents of a file as a payload and use it as the request body in a curl command by using option -d @requestfile - @ and the path to the file.

curl -X POST https://api.restful-api.dev/objects \
     -d @request.json \
     -H "Content-Type: application/json"

and file request.json in current directory

{
   "name": "Apple MacBook Pro 16",
   "data": {
      "year": 2019,
      "price": 1849.99,
      "CPU model": "Intel Core i9",
      "Hard disk size": "1 TB"
   }
}

Write response data to file

We can write the response data to a file using curl, you can use the -o or --output option followed by the file name.

curl https://api.restful-api.dev/objects -o response.json

Hurray! 🥳

We've covered the basics of making API requests with cURL and different HTTP methods. But there is a lot more!

I recently publish this article in polish on my blog:
Tutorial: Jak testować API za pomocą cURL?