How to make API request from command line with CURL
Tags: curl, https, api, request
Published: 2020-04-09 14:44:02

---
title: How to make API request from command line with CURL
published: true
description: Getting started with cURL HTTP request 
tags: cURL, https, api, request
---

# Why learn it?
cURL (Client URL) is a powerful command line tool for working with URLs. 

If you want to test API outputs for your programs, you can use softwares like [Advanced REST Client](https://advancedrestclient.com/), [POSTMAN](https://www.postman.com/), or [Postwoman](https://postwoman.io/). But if you want to do something quick, universal (easily installed in most OS), and also as powerful, you can use cURL. It takes a little more learning, but it is worth it. 

*Fun fact: someone suggested to revise the abbreviation to use recursive acronym.*

```
"Curl Url Request Library" (CURL)
```
*Which, when expanded, becomes:*
```
Curl Url Request Library Url Request Library -> 
Curl Url Request Library Url Request Library Url Request Library ->
Curl Url Request Library Url Request Library Url Request Library Url Request Library ->
... etc
```
cURL can be used with many protocols: 
```
DICT, FILE, FTP, FTPS, GOPHER, HTTP, HTTPS, IMAP, IMAPS, LDAP, LDAPS, POP3, POP3S, RTMP, RTSP, SCP, SFTP, SMB, SMBS, SMTP, SMTPS, TELNET, TFTP
```
I will cover only **one** here, `HTTPS`, because I think that will be the most useful ones for testing APIs (another useful one to learn is FTP). This article is a basic introduction to cURL. If you wish to learn more, check out [resources](#resources). 

I will use [jsonplaceholder](https://jsonplaceholder.typicode.com/) site throughout this article. Let's get started!


# Basic usage - cURL with GET
The basic syntax is:
```
curl your-url
```
For example:
```
curl https://jsonplaceholder.typicode.com/posts
```
cURL will return web page response.

## cURL with query params
Sometimes we need to use query params to filter our search. There is no additional option that we need to pass. Recall that query string params have the following syntax:
```
?param1=value1&param2=value2&paramN=valueN: 
```
For example:
```
curl https://jsonplaceholder.typicode.com/posts?userId=2&id=19
```

## cURL with header information
If you want to see header **i**nformation about your request, add `-i `:

```
curl -i https://jsonplaceholder.typicode.com/posts?userId=2&id=19
```
It will add something like:
```
HTTP/2 200
date: Tue, 07 Apr 2020 12:47:16 GMT
content-type: application/json; charset=utf-8
set-cookie: __cfduid=d995d97cc8c7b809dbd5a490b2db28e2f1586263636; expires=Thu, 07-May-20 12:47:16 GMT; path=/; domain=.typicode.com; 
...
server: cloudflare
cf-ray: 5803db316c66f19e-ATL

// Endpoint response here
```


## cURL + downloading file
You can download file with `-O` option. On today's google main page, I see this cool gif and I want to download it.

![Google main page screenshot on April 8th 2020](https://dev-to-uploads.s3.amazonaws.com/i/joe9d5g2sj7g7v1fg610.png)

Once you locate the URL with inspect, you can download it with:

```
curl -O https://www.google.com/logos/doodles/2020/thank-you-emergency-services-workers-6753651837108755-law.gif
```

It downloads to your current directory where you run that command.

If you want to rename your file, you can use `-o`. The syntax is `curl -o new-file-name file-location-url `. For example:

```
curl -o iggy-google-image.gif  https://www.google.com/logos/doodles/2020/thank-you-emergency-services-workers-6753651837108755-law.gif
```

You don't have to save it to current location. You can change its directory and file, like:

```
curl -o ~/Images/iggy-google-image.gif https://www.google.com/logos/doodles/2020/thank-you-emergency-services-workers-6753651837108755-law.gif
```

# cURL with POST
By default cURL runs a GET request. To use different HTTPS method, you can use `-X` (`--request`). To do POST request with cURL, the syntax is:
```
curl -X POST my-url
```
Btw, our GET cURL earlier:
```
curl https://jsonplaceholder.typicode.com/posts
```

The code above is technically the same as `-X GET`, because if we don't explicitly specify, it will default to GET:

```
curl -X GET https://jsonplaceholder.typicode.com/posts
```

## Sending data (`-d`)
We probably can't do much with POST if we just do `curl -X POST my-url`. We need to pass it some data in our request body. To pass data in cURL, use `-d`. For example:
```
curl -X POST -d 'title=test title&body=no body' https://jsonplaceholder.typicode.com/posts
```

If you notice, the format of our body is similar to query params: `key=value&key2=value2&...`

To pass JSON type data in body:
```
curl -X POST -d '{"title": "hello json"}' https://jsonplaceholder.typicode.com/posts
```

## Adding header
When we are sending data, we may need to include header. For example, to notify the server that we are sending JSON, we add `"Content-type: application/json"`. We can use `-H`.

This is what our request looks like with header added:

```
curl -X POST -d '{"title": "hello json"}' -H "Content-type: application/json" https://jsonplaceholder.typicode.com/posts
```

You can add multiple headers with cURL by having multiple -H in one request:

```
curl -X POST -d '{"title": "hello json"}' -H "Content-type: application/json" -H "Accept-Charset: utf-8" -H "Accept-Language: en-US" https://jsonplaceholder.typicode.com/posts
```

# cURL with PUT
Just like POST, we can do PUT request:

```
curl -X PUT -d '{"title": "hello put"}' https://jsonplaceholder.typicode.com/posts/1
```

# cURL with PATCH
Curl also works with PATCH:
```
curl -X PATCH -d '{"title": "hello patch"}' https://jsonplaceholder.typicode.com/posts/1
```

# cURL with DELETE
Curl works with DELETE:
```
curl -X DELETE https://jsonplaceholder.typicode.com/posts/1
```

# Conclusion
This is a good place to stop. This article provides a guide how to get started with cURL. There are many more features I did not cover. I would suggest checking out the [resources](#resources) below to learn more.

Thanks for reading. Happy coding!

<a name="resources"></a>
# Resources
- [How to start using Curl and why: a hands-on introduction](https://www.freecodecamp.org/news/how-to-start-using-curl-and-why-a-hands-on-introduction-ea1c913caaaa/)
- [Using curl to automate HTTP jobs](https://curl.haxx.se/docs/httpscripting.html)
- [Everything curl](https://ec.haxx.se/)
- [cURL manpage](https://curl.haxx.se/docs/manpage.html)