What Is cURL and How Does It Work with APIs

I wanted to share something about this tool because, although it’s incredibly useful, many people in tech still don’t know much about it — and honestly, I didn’t either at first.

I first heard about curl while debugging an API issue. When a senior developer asked me to “send the curl” and I froze. I messed it up — it was a bit embarrassing — but after that experience (and some trial and error), I realized how simple and useful it really is.

If you’re new to curl too, this post will give you a beginner-friendly intro so you can start using it confidently. Let’s start!

What is curl?

curl (short for Client URL) is a command-line tool that lets you send and receive data from servers using a URL. It’s widely used to test APIs and interact with HTTP endpoints without needing a frontend, browser, or tools like Postman. You can use it from a terminal on Linux, macOS, and even Windows (either installed directly or via Git Bash or WSL).

curl supports many protocols: HTTP, HTTPS, FTP, and more, but today its most common use is API testing over HTTP/HTTPS.

For more info, check out the official docs:

What Can You Do with curl?

Typical use cases include:

  • Quickly test an API endpoint
  • Send a POST request with JSON data
  • Add headers such as authentication tokens
  • Download files from a URL
  • Debug errors directly from your terminal

It’s especially handy for developers and QAs who want to test services independently of the UI.

Basic curl Syntax

The basic structure of a curl command is:

curl [options] [URL]

Breaking it down:

  • curl: the command itself
  • [options]: flags or parameters (HTTP method, headers, body, etc.)
  • [URL]: the endpoint you’re targeting

Real Examples Using restful-booker API

Here are some practical examples using the restful-booker API:

1. Simple GET request — Retrieve all bookings

curl https://restful-booker.herokuapp.com/booking

This fetches a list of all booking IDs.

2. GET request — Retrieve details of booking ID 1

curl https://restful-booker.herokuapp.com/booking/1

Returns detailed information for booking ID 1.

3. POST request — Create a new booking

curl -X POST https://restful-booker.herokuapp.com/booking \
  -H "Content-Type: application/json" \
  -d '{
        "firstname" : "John",
        "lastname" : "Doe",
        "totalprice" : 150,
        "depositpaid" : true,
        "bookingdates" : {
            "checkin" : "2025-09-01",
            "checkout" : "2025-09-10"
        },
        "additionalneeds" : "Breakfast"
      }'

Explanation:

  • -X POST — HTTP method
  • -H — header specifying JSON content
  • -d — data payload with booking details

4. Authenticate and get a token (required for update/delete)

curl -X POST https://restful-booker.herokuapp.com/auth \
  -H "Content-Type: application/json" \
  -d '{"username": "admin", "password": "password123"}'

This returns a JSON with a token to use for authorized requests.

5. PUT request — Update booking ID 1 (requires token)

curl -X PUT https://restful-booker.herokuapp.com/booking/1 \
  -H "Content-Type: application/json" \
  -H "Cookie: token=YOUR_TOKEN_HERE" \
  -d '{
        "firstname" : "Jane",
        "lastname" : "Doe",
        "totalprice" : 200,
        "depositpaid" : false,
        "bookingdates" : {
            "checkin" : "2025-09-05",
            "checkout" : "2025-09-12"
        },
        "additionalneeds" : "Late checkout"
      }'

Replace YOUR_TOKEN_HERE with the token from the previous step.

6. Verbose mode — See full request and response

curl -v https://restful-booker.herokuapp.com/booking/1

This prints detailed info about the request and response which is helpful for debugging.

How to Check if curl Is Installed

Most Linux and macOS systems come with curl preinstalled. Run:

curl --version

If it’s not installed on Windows, you can download it from https://curl.se or use Git Bash, which usually includes it.

Not a Fan of Terminals? Use These Alternatives:

  • Postman: very popular, go-to alternative for API testing
  • HTTPie: Terminal-based but more user-friendly than curl
  • REST Client (VS Code extension): Run HTTP requests inside VS Code

Why Should You Care?

Even though there are tools that make things easier than using curl in the console, this tool is still worth understanding since it can give you direct visibility into what happens behind the scenes:

  • Reproduce backend issues without clicking through the UI
  • Verify if issues come from the API or the frontend
  • Save time debugging or testing multiple scenarios
  • Automate checks by scripting requests

Final Thoughts

Don’t worry if you had no idea what curl was, I didn’t either! But once you start using it, curl quickly becomes an essential, simple, versatile, and lightweight tool in your developer/tester toolbox.

You don’t need to master it all in one day, but learning the basics will save you time, reduce frustration, and help you communicate better with dev teams.

Happy learning, and thank you for reading!