api-request

# HTTP API Requests with curl ## Quick Reference | Action | Command | |--------|---------| | GET | `curl -s URL` | | POST JSON | `curl -s -X POST -H "Content-Type: application/json" -d '{}' URL` | | PUT | `curl -s -X PUT -H "Content-Type: application/json" -d '{}' URL` | | PATCH | `curl -s -X PATCH -H "Content-Type: application/json" -d '{}' URL` | | DELETE | `curl -s -X DELETE URL` | | HEAD | `curl -s -I URL` | ## Essential Options | Option | Long form | Purpose | |--------|-----------|---------| | `-s` | `--silent` | Suppress progress bar (always use for scripting) | | `-S` | `--show-error` | Show errors even when silent | | `-X` | `--request` | HTTP method (GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS) | | `-H` | `--header` | Add request header (`-H "Name: Value"`) | | `-d` | `--data` | Send request body (implies POST) | | `-o` | `--output` | Write response body to file | | `-w` | `--write-out` | Print metadata after transfer (status code, timing) | | `-L` | `--location` | Follow HTTP redirects (3xx) | | `-i` | `--include` | Include response headers in output | | `-I` | `--head` | Fetch headers only (HEAD request) | | `-k` | `--insecure` | Skip TLS certificate verification | | `-v` | `--verbose` | Show full request/response exchange for debugging | | `-f` | `--fail` | Return exit code 22 on HTTP errors (4xx/5xx) | | `-F` | `--form` | Multipart form field (implies POST, multipart/form-data) | | `-u` | `--user` | Basic auth credentials (`user:password`) | ## Timeouts ```bash # Connection timeout (seconds to establish TCP connection) curl -s --connect-timeout 10 URL # Max total time (entire operation including transfer) curl -s --max-time 30 URL # Both together (recommended for robustness) curl -sS --connect-timeout 10 --max-time 30 URL ``` ## GET Requests ```bash # Simple GET curl -s "https://api.example.com/users" # With query parameters (URL-encode special characters) curl -s "https://api.example.com/users?status=active&limit=10" # Follow redirects curl -sL "https://example.com/redirect" # Save response to file curl -sS -o response.json "https://api.example.com/data" ``` ## POST Requests ```bash # JSON body (most common for REST APIs) curl -s -X POST \ -H "Content-Type: application/json" \ -d '{"name": "Alice", "email": "alice@example.com"}' \ "https://api.example.com/users" # JSON body from file curl -s -X POST \ -H "Content-Type: application/json" \ -d @payload.json \ "https://api.example.com/users" # URL-encoded form data curl -s -X POST \ -d "username=alice&password=secret" \ "https://api.example.com/login" # Empty POST (some APIs require POST with no body) curl -s -X POST "https://api.example.com/trigger" ``` ## PUT and PATCH ```bash # PUT — full resource replacement curl -s -X PUT \ -H "Content-Type: application/json" \ -d '{"name": "Alice", "email": "alice@new.com", "role": "admin"}' \ "https://api.example.com/users/42" # PATCH — partial update curl -s -X PATCH \ -H "Content-Type: application/json" \ -d '{"email": "alice@new.com"}' \ "https://api.example.com/users/42" ``` ## DELETE ```bash # Simple DELETE curl -s -X DELETE "https://api.example.com/users/42" # DELETE with body (some APIs require it) curl -s -X DELETE \ -H "Content-Type: application/json" \ -d '{"reason": "duplicate"}' \ "https://api.example.com/users/42" ``` ## Authentication ```bash # Bearer token (OAuth2, JWT) curl -s -H "Authorization: Bearer eyJhbGciOi..." "https://api.example.com/me" # API key in header curl -s -H "X-API-Key: abc123" "https://api.example.com/data" # API key as query parameter curl -s "https://api.example.com/data?api_key=abc123" # Basic auth (user:password) curl -s -u "admin:secret" "https://api.example.com/admin" # Basic auth with prompt for password (interactive) curl -s -u "admin" "https://api.example.com/admin" ``` ## File Upload ```bash # Single file upload (multipart/form-data) curl -s -F "file=@/path/to/document.pdf" "https://api.example.com/upload" # File with explicit content type curl -s -F "file=@photo.jpg;type=image/jpeg" "https://api.example.com/upload" # File with additional form fields curl -s \ -F "file=@report.pdf" \ -F "title=Q4 Report" \ -F "category=finance" \ "https://api.example.com/documents" # Multiple files curl -s \ -F "files=@file1.txt" \ -F "files=@file2.txt" \ "https://api.example.com/batch-upload" # Raw binary upload (PUT) curl -s -X PUT \ -H "Content-Type: application/octet-stream" \ --data-binary @image.png \ "https://api.example.com/files/image.png" ``` ## Response Handling ```bash # Get HTTP status code only curl -s -o /dev/null -w "%{http_code}" "https://api.example.com/health" # Get status code + response body curl -s -w "\n%{http_code}" "https://api.example.com/users" # Get response headers + body curl -si "https://api.example.com/users" # Detailed timing info curl -s -o /dev/null -w "DNS: %{time_namelookup}s\nConnect: %{time_connect}s\nTLS: %{time_appconnect}s\nTotal: %{time_total}s\nStatus: %{http_code}\n" "https://api.example.com" # Pretty-print JSON response (pipe to jq) curl -s "https://api.example.com/users" | jq . # Extract specific field from JSON curl -s "https://api.example.com/users/1" | jq -r '.email' # Response headers only curl -sI "https://api.example.com/users" ``` ## Common Patterns ### Pagination ```bash # Offset-based curl -s "https://api.example.com/items?offset=0&limit=50" curl -s "https://api.example.com/items?offset=50&limit=50" # Page-based curl -s "https://api.example.com/items?page=1&per_page=25" # Cursor-based (use cursor from previous response) curl -s "https://api.example.com/items?cursor=eyJpZCI6MTAwfQ" ``` ### Retry on Failure ```bash # Retry up to 3 times with exponential backoff curl -s --retry 3 --retry-delay 2 --retry-max-time 30 "https://api.example.com/data" # Retry only on specific errors (transient) curl -s --retry 3 --retry-all-errors "https://api.example.com/data" ``` ### Conditional Requests ```bash # If-Modified-Since (returns 304 if unchanged) curl -s -H "If-Modified-Since: Mon, 01 Jan 2024 00:00:00 GMT" "https://api.example.com/data" # ETag-based caching curl -s -H 'If-None-Match: "abc123"' "https://api.example.com/data" ``` ### GraphQL ```bash curl -s -X POST \ -H "Content-Type: application/json" \ -d '{"query": "{ users(first: 10) { id name email } }"}' \ "https://api.example.com/graphql" ``` ## Debugging ```bash # Verbose output (shows full request/response headers and TLS handshake) curl -v "https://api.example.com/users" 2>&1 # Trace to file (hex dump of all data) curl --trace trace.log "https://api.example.com/users" # Show only response headers curl -sI "https://api.example.com/users" # Dump request and response headers to file curl -sS -D headers.txt -o body.json "https://api.example.com/users" ``` ## HTTP Status Code Reference | Range | Meaning | Common Codes | |-------|---------|-------------| | 2xx | Success | 200 OK, 201 Created, 204 No Content | | 3xx | Redirect | 301 Moved, 302 Found, 304 Not Modified | | 4xx | Client error | 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 409 Conflict, 422 Unprocessable, 429 Too Many Requests | | 5xx | Server error | 500 Internal Error, 502 Bad Gateway, 503 Unavailable, 504 Timeout | ## Important Notes - Always use `-s` (silent) to suppress the progress bar in scripts - Use `-sS` to suppress progress but still show errors - When sending JSON, always set `-H "Content-Type: application/json"` - Use `-L` to follow redirects (curl does not follow them by default) - Use `--connect-timeout` and `--max-time` for robustness against hanging requests - Pipe to `jq .` for readable JSON output, or `jq -r '.field'` to extract values - Use `-f` (fail) when you need curl to return a non-zero exit code on HTTP errors - For binary data in POST body, use `--data-binary` instead of `-d` (which strips newlines) - Special characters in URLs should be percent-encoded (spaces = `%20`, `&` = `%26`) - Use single quotes around JSON payloads to avoid shell variable expansion issues