DEV Community

Cover image for The Simplest Guide to Curl for REST API Requests
Rita {FlyNerd} Lyczywek
Rita {FlyNerd} Lyczywek

Posted on • Updated on

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

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
Enter fullscreen mode Exit fullscreen mode

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
   } ...
]
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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

curl https://api.restful-api.dev/objects/1/
Enter fullscreen mode Exit fullscreen mode

Url with query params. Fetch item by id:

https://api.restful-api.dev/objects?id=3
Enter fullscreen mode Exit fullscreen mode

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

curl https://dev.to/api/articles?username=ritaly
Enter fullscreen mode Exit fullscreen mode

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"
Enter fullscreen mode Exit fullscreen mode

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"
   }
}
Enter fullscreen mode Exit fullscreen mode

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"}}' 
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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"}}'
Enter fullscreen mode Exit fullscreen mode

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"}'
Enter fullscreen mode Exit fullscreen mode

Check your record:

curl https://api.restful-api.dev/objects/:id
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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"
Enter fullscreen mode Exit fullscreen mode

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"
   }
}
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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?

Top comments (2)

Collapse
 
proteinovij profile image
proteinovij

Thanks for tutorial! This was very useful!

Collapse
 
ritaly profile image
Rita {FlyNerd} Lyczywek

Happy it is useful! :D