curl in 10 examples: test any API from the terminal

Tags: Linux, API, Networking, Beginner

Introduction – what is curl and why you need it

curl (Client URL) is a command‑line tool that talks HTTP, HTTPS, FTP, and many other protocols. It’s installed by default on most Linux distributions, macOS, and even Windows Subsystem for Linux.

• What it does: send a request to a URL and print the raw response.
• Why it matters: you can verify an API’s behaviour without writing code, debug authentication problems, or automate health checks in scripts.

This tutorial is for anyone who can open a terminal and type a command – from a brand‑new developer to a seasoned sysadmin who wants a quick way to poke an API.

Part 1 – Core curl concepts

How curl builds a request

1. URL parsing – the scheme (http/https) determines the port and TLS usage.
2. Method selection – default is GET. Adding -X or -d changes it.
3. Headers – curl adds a few defaults (User-Agent, Accept). You can replace or add with -H.
4. Body – only sent for methods that support it (POST, PUT, PATCH).

Understanding these steps makes the examples below easier to follow.

Part 2 – 10 practical examples with httpbin.org

httpbin.org is a free service that echoes back whatever you send it. It’s perfect for learning curl because you can see the exact request curl generated.

Running the examples

Open a terminal, copy a line, and press Enter. All commands are self‑contained – no extra setup required.

Example 5 explained step‑by‑step

curl -X POST \
     -H "Content-Type: application/json" \
     -d '{"title":"curl","views":100}' \
     https://httpbin.org/post

• -X POST forces the POST method.
• -H "Content-Type: application/json" tells the server we’re sending JSON.
• -d '{...}' supplies the JSON body.
• The response’s json field will be exactly the payload we sent, confirming that the request arrived intact.

Part 3 – Hands‑on example: a tiny API health‑check script

Below is a ready‑to‑run Bash script that checks three common aspects of any REST endpoint:

1. Reachability (GET /status or fallback to /get).
2. JSON validity (expects a JSON response).
3. Response time (fails if > 2 seconds).

#!/usr/bin/env bash
# healthcheck.sh – test an API endpoint with curl
# Usage: ./healthcheck.sh https://httpbin.org/get

set -euo pipefail

URL="${1:-https://httpbin.org/get}"
MAX_MS=2000   # 2 seconds

echo "🔎 Checking $URL …"

# 1️⃣ Reachability & timing
TIME_MS=$(curl -s -o /dev/null -w "%{time_total_ms}" "$URL")
if (( $(echo "$TIME_MS > $MAX_MS" | bc -l) )); then
  echo "❌ Too slow: ${TIME_MS}ms (limit ${MAX_MS}ms)"
  exit 1
fi
echo "✅ Response time: ${TIME_MS}ms"

# 2️⃣ HTTP status code
STATUS=$(curl -s -o /dev/null -w "%{http_code}" "$URL")
if [[ "$STATUS" != 2* ]]; then
  echo "❌ Unexpected status: $STATUS"
  exit 1
fi
echo "✅ HTTP status: $STATUS"

# 3️⃣ JSON validation (optional)
if curl -s "$URL" | jq . >/dev/null 2>&1; then
  echo "✅ Valid JSON returned"
else
  echo "❌ Response is not valid JSON"
  exit 1
fi

echo "🎉 All checks passed!"

How to run

chmod +x healthcheck.sh
./healthcheck.sh https://httpbin.org/get

If everything is fine you’ll see:

🔎 Checking https://httpbin.org/get …
✅ Response time: 123ms
✅ HTTP status: 200
✅ Valid JSON returned
🎉 All checks passed!

Feel free to replace the URL with any of your own services.

Common mistakes & troubleshooting

Try it yourself

Exercise: Use curl to send a PATCH request that updates a JSON field on https://httpbin.org/patch. Include a custom header X-Exercise: true and verify that the response’s json contains your changes.

curl -X PATCH \
     -H "Content-Type: application/json" \
     -H "X-Exercise: true" \
     -d '{"status":"completed"}' \
     https://httpbin.org/patch

Check that the json object in the output matches the payload and that headers shows X-Exercise: true.

What’s next

• Batch testing: combine curl with xargs or GNU Parallel to hit many endpoints at once.
• OAuth 2.0 flows: use curl to exchange client credentials for an access token.
• Saving and reusing cookies: explore -c and -b options for session handling.
• Performance profiling: integrate curl with time or hyperfine for benchmark scripts.

Keep experimenting, and soon you’ll be comfortable debugging any HTTP API right from your terminal.

Bookmark this guide for quick reference.