curl: One Tool, Every System
The browser watches and peeks; now you get the tool that does exactly what you say. curl is a small command-line program that sends precisely the request you describe and prints precisely what comes back. It is already installed on effectively every computer — Windows, Mac, Linux — and it is the shared language of every API's documentation on earth. When docs show an example request, they show it as a curl command. When a support engineer asks "what did you send?", the answer they want is a curl command.
If you have never opened a terminal, this is the page where that changes, gently. The terminal is a window where you type a command and the computer runs it — that is the whole idea. On Windows it is called Terminal or PowerShell; on a Mac, Terminal. Open it, and you are three keystrokes from your first deliberate API call. (One Windows-only catch: in Windows PowerShell — the one Windows opens by default, as opposed to the separately installed PowerShell 7 — plain curl is a nickname for a different tool. Type curl.exe and everything behaves as this book describes.)
curl https://api.tandem.example/v1/stations/st_014
Type it, press Enter, and the station object for Old Market prints in the terminal — the same JSON from two pages ago. The difference is who is in charge: the browser filled in everything for you and hid the seams; curl sends what you say, only what you say, and shows everything.
Seeing the Whole Conversation
Bare curl prints only the response body. Two flags — options you add to a command, each starting with a dash — open the rest up. Add -i and the response headers print above the body: the status line, the Content-Type, everything Chapter 2 taught you to read. Add -v instead and curl narrates the entire exchange — the request it sent, line by line, then the response as it arrived. The first time you run curl -v, Chapter 2 stops being theory: there on your screen is the request line, the Host header, the verdict, in the flesh.
The Whole Toolkit: Six Flags
This book uses six curl flags, total, and this is the page that lists them. -i — include response headers. -v — narrate everything. -H — add a header of your choosing, which is how the key travels from Chapter 5 on. -X — choose the verb, when it is not GET. -d — send a body, which makes a request a delivery. -L — follow a 3xx redirect to its forwarding address. That is the entire kit. Everything this book does at any counter, it does with these six.
Why Every API's Documentation Speaks curl
One line of curl states a complete, reproducible request: address, verb, headers, body — nothing hidden in a tool's settings, nothing dependent on what was clicked earlier. That is why docs give examples in it, why bug reports are trusted when they include one, and why Chapter 7's debugging checklist begins with "reproduce it with one curl." The command is not a programmer's affectation; it is the field's way of saying exactly what happened.
- "The command line is dangerous — one typo and something breaks." curl sends the request you typed and prints text. While you are reading — and everything before the chapter's last page only reads — the blast radius of a typo is an error message, and Chapter 7 makes even those friendly.
- "curl printed nothing, so it failed." Quiet output often is the answer — an empty list, or a success with nothing to say (Chapter 2's 204). Add -i and the status line will tell you what actually happened.
- "I need a proper GUI tool or an SDK to do real API work." The GUI tools are wrappers around this same request, and Chapter 10 tours them from strength. curl is the floor everything stands on — and the floor is enough for this entire book.
- "I have to memorize dozens of flags." Six. This book uses six, they are listed above, and by Chapter 7 your fingers will know them without you.
- From this page on, every example in the book is runnable by you (Windows readers: see the shell note on the POST page). From here the book is something you run rather than something you read, which is the difference between knowing about APIs and working with them.
- "Send me the curl" is how professionals ask each other for reproducible facts. Being able to answer marks you, instantly, as someone worth helping efficiently.
Knowledge Check
What does bare curl <url> do?
- Sends a GET request to that address and prints the response body
- Downloads the file at that address and saves it to your computer
- Opens the address in a small built-in browser window for inspection
- Tests whether the server is reachable and reports yes or no
Which flag adds a header of your choosing to the request?
- -i, which is how the key will travel in Chapter 5
- -H, which is how the key will travel in Chapter 5
- -d, which is how the key will travel in Chapter 5
- -X, which is how the key will travel in Chapter 5
Why do all API docs give their examples as curl commands?
- Because API providers earn a commission when readers install curl
- Because most readers of documentation have no other tools available
- Because one curl line states the complete request, reproducible by anyone anywhere
- Because curl commands only work on the operating system the docs target
You run a curl command and nothing prints. What is the professional next move?
- Run the same command again immediately in case the first attempt was unlucky
- Reinstall curl, since silent output means the tool is broken
- Re-run it with -i and read the status line that comes back
- Email the provider's support to ask why the API returned nothing
You got correct