Lam Nguyen

August 24, 2023

 • 2 min read

0

What is curl?

Make basic requests with the curl command-line tool

What is curl?

curl is a command-line tool for transferring data from or to a server. It supports multiple protocols, including HTTP. In this article, you will learn how to use curl to make requests from the command-line, as well as how to parse the responses to those requests.

For example, say you are building a cryptocurrency trading app. If you built the back-end API first, you could access your exchange rate data before even building a webpage:

$ curl https://api.coinbase.com/v2/prices/BTC-USD/buy

{
  "data": {
    "base": "BTC",
    "currency": "USD",
    "amount": "33006.51"
  }
}

Making GET Requests

The most basic curl command is:

curl http://example.com/abc

Specifying a Request’s HTTP Method Using -X

By default, curl makes GET requests, but you can use the -X option (short for —request) followed by the HTTP verb (eg. PUT, POST, DELETE, etc.) of your choice to make other types of requests.

For example, to make a DELETE request to http://sample-api.com/sample-resource/id, you would run:

curl -X DELETE http://sample-api.com/sample-resource/id

OR:

curl --request DELETE http://sample-api.com/sample-resource/id

Adding Data to the Request Body Using -d

To send data in the body of a request made with curl, you can use the -d option (short for —data) followed by the data you wish to send. For example, to update the name of the user with id=1, run:

curl -X PUT -d "username=Lily" http://sample-api.com/users/1

Additional key-value pairs can be added with the ampersand & symbol:

curl -X PUT -d "username=Lily&height=180" http://sample-api.com/users/1

Note that if you include the -d option and do not specify an HTTP verb, curl will default to sending a POST request. That means that

curl -X POST -d "username=Lily" http://sample-api.com/users

AND:

curl -d "username=Lily" http://sample-api.com/users

are equivalent.

Setting the Request’s Content Type Using -H

By default, curl sends POST/PUT requests with the content-type application/x-www-form-urlencoded. If you are using curl to make a request to an API that expects to receive data in JSON format, you must set the request’s content-type to application/json by adding a request heade

Use the -H (short for —header) option, followed by the header you wish to add to your request, to specify the request’s content-type like so:

curl -d "{ \"username\": \"Lily\" }" -H "Content-Type: application/json" http://sample-api.com/users

Parsing Server Responses Using -i

Adding the -i option (short for —include) to your curl commands will cause curl to print the response header to the command shell in addition to the response body.

$ curl -i https://api.coinbase.com/v2/prices/BTC-USD/buy

HTTP/2 200
date: ...
content-type: ...
...

Some of the client errors you are most likely to encounter include

• 401, which indicates that the client is not authenticated and therefore not allowed to access the specified resource
• 403, which indicates that the client is authenticated but not permitted to view the specified resource
• 404, which indicates that the specified resource cannot be found on the server

Some HTTP response status codes