Terminal · foundation
HTTP requests with curl
curl is a command-line data-transfer client that uses a URL to select a protocol and exposes options for constructing requests, inspecting transfers, handling failures, and writing response data. For HTTP, its defaults and options map to request methods, fields, content, redirects, and authentication.
Why it matters
A carefully written curl command is a reproducible probe across DNS, connection, TLS, HTTP, and application layers. It can isolate failures more precisely than testing through a full browser or app.
Mental model
How to reason about http requests with curl
Start with a URL, then deliberately add request semantics and output policy. Keep three results separate: curl's process exit status, the HTTP response status, and the response content.
Analogy
curl is a configurable test courier: you specify the destination, envelope fields, payload, and which delivery or response details should count as failure.
Examples
See the boundary, not just the happy path
Worked example · Fetch JSON and fail on HTTP errors
curl --fail-with-body --silent --show-error -H 'Accept: application/json' https://api.example.com/v1/statusThe request advertises JSON acceptance. --fail-with-body makes HTTP 400 or greater produce a nonzero curl status while retaining the response body; --show-error preserves diagnostics despite silent progress output.
Worked example · POST a JSON representation
curl --fail-with-body -H 'Content-Type: application/json' --data '{"name":"Ada"}' https://api.example.com/v1/users--data supplies request content and makes curl use POST unless another method is selected. Content-Type describes the representation being sent; it does not ask for a JSON response, which would use Accept.
Avoid · Execute an unreviewed download
curl -fsSL https://unknown.example/install.sh | shPiping a network response directly into a shell removes the opportunity to inspect, authenticate independently, checksum, or archive the exact code before execution. Download and verify first.
Common mistakes
Misconceptions to remove early
Assuming HTTP 500 makes curl fail by default
A completed HTTP transfer normally gives curl exit status zero even for an HTTP error response. Use --fail or --fail-with-body when scripts should treat applicable 4xx/5xx statuses as failures.
Forcing a method without matching request semantics
-X changes the method token but does not automatically configure content or redirect behavior appropriately. Prefer semantic options such as --data, --head, or --request-target when they express the intended operation.
Quick check
Can you predict the result?
1. Why add --fail-with-body to curl in an automated check?
- • It makes applicable HTTP error statuses produce a nonzero curl exit while preserving the response body.
- • It disables TLS certificate validation.
- • It retries every request until it receives HTTP 200.
2. What is the difference between Content-Type and Accept in an HTTP request?
Keep building