The Developer’s Swiss Army Knife
Modern software development is built entirely on APIs (Application Programming Interfaces). When your weather app shows the temperature, it is talking to a weather API. When a website processes a credit card, it is talking to Stripe’s API. These servers communicate by sending small packets of data (usually JSON) back and forth across the internet.
If you are building an application and the API suddenly stops working, you need to diagnose the problem. The amateur approach is to write a script in Python or Node.js to try and force a connection, but this introduces too many variables (Is your code wrong, or is the server down?).
The professional solution is to strip away all the code and talk to the server directly from the command line. The tool for this job is curl (Client URL). It is the undisputed industry standard for sending HTTP requests and testing API endpoints directly from the Linux terminal.
Basic Operations (The GET Request)
The simplest way to use curl is to fetch the raw data from a website, exactly as a web browser does under the hood. This is known as a GET request.
To see the raw HTML of a website, simply type curl followed by the URL:
curl https://example.comThe terminal will instantly spit out the raw HTML code of the homepage. While reading raw HTML is not very useful, this same command is how you test basic API health endpoints.
If an API has a public endpoint to check the current Bitcoin price, you can fetch it instantly:
curl https://api.coindesk.com/v1/bpi/currentprice.jsonThe terminal will return the raw JSON data, proving that the API server is alive and responding.
Advanced Operations (The POST Request)
APIs do not just return data; they accept data. If you need to submit a form, create a new user, or send a command to a server, you must use a POST request. This requires sending data along with your URL.
1. Adding Headers (-H)
When talking to modern APIs, you almost always need to tell the server what format your data is in (usually JSON) and provide an authentication token (so the server knows who you are).
You do this using the -H (Header) flag.
curl -H "Content-Type: application/json" -H "Authorization: Bearer my_secret_token" https://api.example.com/users2. Adding the Data Payload (-d)
Now that the server knows who you are, you must send the actual data payload. You use the -d (Data) flag for this.
Let’s create a new user named “John” by sending a JSON payload to the API.
curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer my_secret_token" \
-d '{"name": "John", "email": "[email protected]"}' \
https://api.example.com/users(Note: We use the -X POST flag to explicitly tell curl we are submitting data, not just requesting it).
When you press Enter, the terminal will instantly display the server’s response. If it says {"status": "success", "id": 101}, you know definitively that the API works. If your Python script is failing to create a user, you now know the bug is in your Python code, not the API server.
Debugging Connections (-v)
Sometimes, the server doesn’t respond at all. The connection just hangs. To figure out exactly where the connection is failing (e.g., DNS resolution, SSL handshake, or server timeout), add the -v (Verbose) flag.
curl -v https://api.example.comThe output will show every single micro-step of the connection process. Lines starting with * show what curl is doing locally, > shows what curl is sending to the server, and < shows exactly what the server is sending back. This level of detail is invaluable for diagnosing complex network issues.
Do not write complex scripts to test simple server connections. The curl command allows you to rapidly construct custom HTTP requests, inject authentication headers, and read raw JSON responses directly in the terminal, making it an essential diagnostic tool for modern web development.