Hexlet logo

HTTP API

Theory: CURL

One browser isn't enough for testing HTTP APIs. Browsers can be used only in simple situations when you don't need to expose the headers and make requests other than GET. In all other cases, you need more powerful and more specialized tools.

Curl is a command line utility created back in 1998. It is actively used for downloading files and in automation scripts. In the API documentation of many services, there are examples of how to execute a request using curl, along with the description of the service itself.

It's included in some operating systems by default. If you don't have it, install it using this command:

# MacOS
brew install curl
# Ubuntu, Windows (WSL)
apt install curl

Make sure everything works:

curl --version
curl 7.79.1

The easiest way to use curl is to make a GET request to a website:

curl https://code-basics.com
# The answer body will appear here

In this case, curl will print the body of the response, which is the HTML of the site in our case. You can save it to a file by redirecting it:

curl https://code-basics.com > code-basics.html

If we want to see the response headers, the query becomes:

# --head - request with the HEAD method
curl --head https://code-basics.com

HTTP/2 200
date: Thu, 28 Apr 2022 22:19:39 GMT
content-type: text/html; charset=utf-8
cache-control: max-age=0, private, must-revalidate

In this case, curl sends a HEAD request, which the server should respond to by returning the headers without the body.

According to the specification, the headers returned when a made HEAD request must be the same as for a GET request, but the actual response is not.

Therefore, it's better to perform a GET request for accuracy:

# -X, --request -Sets the query method
# --In this case, the head ignores the body when outputting
curl --head -X GET https://code-basics.com

HTTP/2 200
date: Thu, 28 Apr 2022 22:19:39 GMT
content-type: text/html; charset=utf-8
cache-control: max-age=0, private, must-revalidate

If you want to see the answer and also the query, then the --verbose flag is what you need. It will show everything, including the body of the answer:

# The output is shortened
# -v, --verbose
curl -v https://code-basics.com
*   Trying 104.26.0.21:443...
* Connected to code-basics.com (104.26.0.21) port 443 (#0)
* SSL connection using TLSv1.3 / AEAD-AES256-GCM-SHA384
> GET / HTTP/2
> Host: code-basics.com
> user-agent: curl/7.79.1
> accept: */*
>
* Connection state changed (MAX_CONCURRENT_STREAMS == 256)!
< HTTP/2 200
< date: Thu, 28 Apr 2022 22:24:06 GMT
< content-type: text/html; charset=utf-8
< referrer-policy: strict-origin-when-cross-origin
< cache-control: max-age=0, private, must-revalidate
<
# There's also a body

Entering headings:

# -H, --header
curl -H "Content-Type: application/json" https://dummyjson.com/users

And the bodies in the query:

# \ - needed to specify multiline code in the terminal
curl -X POST https://dummyjson.com/api/users/add \
   -H "Content-Type: application/json" \
   -d '{ "firstName": "Sam", "age": 100 }'

Recommended programs

Navigation
Theory
Tests