Hello cURL for beginners

We are going to discuss the basics of sending HTTP requests from your terminal. For this, we’ll use cURL, a popular command-line tool for passing data from a client to a server.

Introduction

In this post, we are going to discuss the basics of sending HTTP requests from your terminal. For this, we’ll use cURL, a popular command-line tool for passing data from a client to a server.

If you’ve never used cURL, don’t worry, we’ll cover the syntax and some command samples that can be run from your local machine since we’ll rely on mock endpoints.

The structure of a curl command

A curl command follows the following format:

curl -X [http-method] [options] [url] 

And we can break the syntax down in:

  • [http-method] represents the name of the HTTP Method you want to use. It will default to a GET method if you skip adding the -X [http-method] part. When we have a payload, a request body, the default method used will be a POST. Some valid options are GET, POST, PUT, PATCH, DELETE, HEAD and so forth.
  • [options] are whatever command-line arguments you need to use. Some of the most popular ones are:
    • -i or -I to get back the response headers (-I will retrieve ONLY the response headers).
    • -H "name:value" argument is used to add or change a header value. It will work for as many headers as you need.
    • -A "value" if you need to define a user agent.
    • --compressed to request compressed data, if the server supports it.
    • -o file and -O file will store the response in the defined file
    • -v stands for verbose and you'll get a lot more information in the terminal.
    • -d "value" or -d file to send a particular payload or read it from a file
    • --data-urlencode="[name]=value" to send URL-encoded data, usually how HTTP form submissions will send it.
    • -F name=@file to upload a file.
    • -m value will add a timeout in seconds.
    • -k or --insecure to ignore the certificate validation, useful when requesting data via HTTPS from servers where the certificate is not yet valid.
    • -L to follow redirects.
  • [url] is self-explanatory, the URL where you want to send your request. A valid value is http://mockbin.org/bin/aac1728d-f76d-452b-87a1-0e9cb193b245.

Request samples using curl

To start, we've created a mock endpoint that we are going to use in our examples using Mockbin. The URL is http://mockbin.org/bin/aac1728d-f76d-452b-87a1-0e9cb193b245.


Let's check that our endpoint is up and running, to retrieve only the response headers:

> curl -I http://mockbin.org/bin/aac1728d-f76d-452b-87a1-0e9cb193b245

//Response:
HTTP/1.1 200 OK
Date: Wed, 01 Sep 2021 19:46:50 GMT
Content-Type: text/html; charset=utf-8
Connection: keep-alive
vary: Accept-Encoding
via: 1.1 vegur
CF-Cache-Status: DYNAMIC
Report-To: {"endpoints":[{"url":"https:\/\/a.nel.cloudflare.com\/report\/v3?s=2JeKxhKJWjmhy1XVHwFqRpXzs9ZTVXKQzQ5Q00WcBLg8lFM8hsXFbMZlOGeJywq0JaTdg2VAZWO9%2FtHrDfm3p8fS%2Fv2sQbVR%2Bc%2FiGjjrTeuwRYZKB7Uk3eaz9bPhiw%3D%3D"}],"group":"cf-nel","max_age":604800}
NEL: {"success_fraction":0,"report_to":"cf-nel","max_age":604800}
Server: cloudflare
CF-RAY: 688101c8ec372794-PRG
alt-svc: h3-27=":443"; ma=86400, h3-28=":443"; ma=86400, h3-29=":443"; ma=86400, h3=":443"; ma=86400

And in order to issue a GET request and retrieve only the payload we can run:

> curl http://mockbin.org/bin/aac1728d-f76d-452b-87a1-0e9cb193b245

//Response:
Hello cURL users

Let's now send a POST request with a JSON body payload. We'll also request a compressed response if possible.

> curl -X POST \
  -H "Content-Type:application/json" \
  -d '{"propertyName":"propertyValue"}' \
  http://mockbin.org/bin/aac1728d-f76d-452b-87a1-0e9cb193b245
  
//Response:
Hello cURL users

To upload a file called file.csv via a POST request the command is:

> touch file.csv
> curl -X POST \
  -F myFile=@file.csv \
  http://mockbin.org/bin/aac1728d-f76d-452b-87a1-0e9cb193b245
  
//Response:
Hello cURL users

And for a DELETE request:

> curl -X DELETE -i http://mockbin.org/bin/aac1728d-f76d-452b-87a1-0e9cb193b245

//Response:
HTTP/1.1 200 OK
Date: Thu, 02 Sep 2021 08:45:40 GMT
Content-Type: text/html; charset=utf-8
Transfer-Encoding: chunked
Connection: keep-alive
vary: Accept-Encoding
via: 1.1 vegur
CF-Cache-Status: DYNAMIC
Report-To: {"endpoints":[{"url":"https:\/\/a.nel.cloudflare.com\/report\/v3?s=Z4tjDYCGgH0Xv4ekmPO1x%2FYYk21stWYFESn5W7xmbrwMkmH0%2FhhOWwwHZ8QD%2Blf2JxJfwUB2U4ev69IYZRejnrifV06ARKAVhPm%2Fcgj5i8%2FdtjiEjwQjZjabUwHE1Q%3D%3D"}],"group":"cf-nel","max_age":604800}
NEL: {"success_fraction":0,"report_to":"cf-nel","max_age":604800}
Server: cloudflare
CF-RAY: 688576a92e4a38bf-VIE
alt-svc: h3-27=":443"; ma=86400, h3-28=":443"; ma=86400, h3-29=":443"; ma=86400, h3=":443"; ma=86400

Hello cURL users

To send a GET request with 3 seconds timeout to an endpoint that will delay the response by 3001ms we can do:

> curl -X GET \
  -m 3 \
  http://mockbin.org/delay/3001
  
//Response:
curl: (28) Operation timed out after 3004 milliseconds with 0 bytes received

Conclusion

We've seen the cURL command format and how we can build requests using some of the most common cURL arguments.

If you want to take your experimentation further, you can:

  1. Build a mock endpoint yourself.
  2. Interact with it via cURL commands
  3. Choose a real REST API, my recommendation is the one that returns a list of beers, and read data via cURL commands.

Subscribe to HTTPULSE

Don’t miss out on the latest issues. Sign up now to get access to the library of members-only issues.
jamie@example.com
Subscribe