The Simplest Guide to Curl for REST API Requests
Tags: curl, api, beginners, webdev
Published: 2023-02-10 20:26:28

---
title: The Simplest Guide to Curl for REST API Requests
published: true
description: Learn how to use curl to make quick and easy REST API requests from the command line in this beginner-friendly guide.
tags: curl, api, beginners, webdev

cover_image: https://dev-to-uploads.s3.amazonaws.com/uploads/articles/sbt2js6ptqkryrwvzf4g.png
# Use a ratio of 100:42 for best results.
# published_at: 2023-01-10 11:23 +0000
---

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](#get-request)
- [POST request](#post-request)
- [PUT request](#put-request)
- [PATCH request](#patch-request)
- [DELETE request](#delete-request)
- [Read request data from file](#write-response-data-to-file)
- [Write response to file](#write-response-data-to-file)

For demo purposes I'm using [{REST-API}](https://restful-api.dev/) - 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

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

and receive response:

```json
[
   {
      "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.

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

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

```bash
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.

```bash
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.

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

-----

### POST request

Create new object with body like this:

```json
{
   "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:

```bash
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: 

```bash
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 

```bash
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`) .

```bash
 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`) .

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

Check your record:

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


### DELETE request

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

```bash
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

```json
{
   "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. 

```bash
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?](https://www.flynerd.pl/2023/02/testowanie-api-curl.html)