The Linux curl Command: My API Debugging Survival Guide
The Linux curl Command: My API Debugging Survival Guide
The production API was returning 500 errors. My junior dev said "curl works fine on my machine." I spent an hour debugging, only to realize he was testing against localhost while I was debugging production.
That's when I learned the hard way: curl is deceptively powerful, and small differences matter.
First Encounter with curl
My initial curl command was simple:
curl https://api.example.com/dataThis worked to test connectivity. But I needed more.
Adding headers
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer token123" \
https://api.example.com/dataPOST request
curl -X POST -d '{"name":"test"}' \
-H "Content-Type: application/json" \
https://api.example.com/dataFollow redirects
curl -L https://short.url/abcThe -L flag follows redirects—essential for testing URL shorteners!
Why curl Confused Me
1. GET vs POST
GET is default. Need -X POST explicitly:
curl -X POST https://api.example.com/endpoint2. Data format
Without -H "Content-Type: application/json", API expects form data:
curl -X POST -d "param1=value1¶m2=value2" \
https://api.example.com/endpointvs:
curl -X POST -d '{"param1":"value1","param2":"value2"}' \
-H "Content-Type: application/json" \
https://api.example.com/endpoint3. Authentication
Basic auth isn't intuitive:
curl -u username:password https://api.example.com/4. SSL verification
Self-signed cert fails:
curl -k https://self-signed.example.com/The -k flag ignores SSL errors (use for testing only!).
curl Commands That Saved My Job
Testing REST APIs
curl -X GET https://api.example.com/users \
-H "Authorization: Bearer token" \
-H "Accept: application/json"GET with headers.
POST with JSON
curl -X POST https://api.example.com/users \
-H "Content-Type: application/json" \
-H "Authorization: Bearer token" \
-d '{"name":"John","email":"john@example.com"}'Debug with verbose
curl -v https://api.example.com/Shows request/response headers, SSL handshake—everything.
Save response to file
curl -o response.json https://api.example.com/dataDownload instead of stdout.
Include cookies
curl -b cookies.txt -c cookies.txt https://api.example.com/-b reads cookies, -c saves them.
Form submission
curl -F "file=@document.pdf" \
-F "description=Test" \
https://upload.example.com/Multipart form upload.
Testing with user agent
curl -A "Mozilla/5.0" https://example.com/Spoof browser.
Silent mode
curl -s https://api.example.com/data | jq .-s suppresses progress meter.
The curl Command Builder: Visual API Testing
API testing with curl has many options—the curl Command Builder helps:
- Visual interface for request type, headers, body
- Quick presets for common API patterns
- Copy with curl/cURL formatting
- Header builder without typos
curl Options Quick Reference
| Flag | What It Does |
|---|---|
-X |
Request method |
-H |
Header |
-d |
POST data |
-F |
Form field |
-u |
Basic auth |
-v |
Verbose |
-k |
Insecure SSL |
-L |
Follow redirects |
-o |
Output file |
-s |
Silent |
-A |
User agent |
-b |
Cookies (read) |
-c |
Cookies (write) |
Debugging SSL Errors
Show certificate info
curl -v https://example.com 2>&1 | grep -A2 "SSL"Verify certificate chain
curl --cacert ca.pem https://example.com/Show all certificates
curl -vvv https://example.com 2>&1 | grep "certificate"Lessons Learned
-
Use -v when debugging — verbose output shows exactly what's happening.
-
Always set Content-Type for POST requests.
-
Use -L for redirects — otherwise you'll miss the final response.
-
Use -s with jq — suppress progress for clean JSON parsing.
-
Test with -k temporarily but remove for production.
Conclusion: curl Is Your API Best Friend
curl went from being a mystery to my favorite debugging tool. The key is understanding headers, methods, and SSL.
The curl Command Builder makes building requests visual—click, test, copy.
