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 systemPATH
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 usesapplication/x-www-form-urlencoded
as the defaultContent-Type
, we change it toJSON
) -
-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?
Top comments (2)
Thanks for tutorial! This was very useful!
Happy it is useful! :D