Curl

About

curl is a command-line tool used to transfer data to or from a server using various internet protocols. It is widely used by developers to test REST APIs, download files, and simulate client requests.

It is short for "Client URL" and supports protocols like HTTP, HTTPS, FTP, SFTP, and more. In API development, curl is commonly used to send HTTP requests and inspect server responses.

Why Use curl?

• To test API endpoints from the terminal

• To simulate real HTTP requests (GET, POST, PUT, DELETE)

• To send custom headers, payloads, or authentication tokens

• To debug issues like authentication failures or incorrect responses

Basic Syntax

curl [options] [URL]

Curl Options

Option	Description
-X or --request <METHOD>	Specifies the HTTP method (GET, POST, PUT, DELETE, etc.)
-H or --header <HEADER>	Adds a custom header (e.g., Content-Type, Authorization)
-d or --data <DATA>	Sends data in the body (used with POST, PUT, etc.)
--data-raw <DATA>	Sends raw, unprocessed data
--data-urlencode <DATA>	Sends URL-encoded data
-F or --form <KEY=VALUE>	Sends form data, including file uploads (multipart/form-data)
-u or --user <user:password>	Uses basic authentication
-o or --output <file>	Saves the response body to a file
-O	Saves the file using the remote file name
-i or --include	Includes response headers in the output
-I or --head	Sends a HEAD request (returns headers only)
-v or --verbose	Prints detailed info for debugging (request/response, SSL handshake, etc.)
-s or --silent	Hides progress bar and error messages
-S or --show-error	Shows error even when --silent is used
-L or --location	Follows redirects (3xx responses)
-k or --insecure	Ignores SSL certificate validation (not recommended in production)
--compressed	Requests a compressed response (e.g., gzip)
--http1.1, --http2, --http3	Forces use of specific HTTP protocol versions
--url <URL>	Specifies the URL explicitly (used in scripts)
--max-time <seconds>	Sets a timeout for the entire request
--connect-timeout <seconds>	Sets timeout for connection phase only
--retry <n>	Automatically retries the request up to n times
-e or --referer <URL>	Sets the Referer header
-A or --user-agent <string>	Sets a custom User-Agent header
--cert <file>	Uses a client certificate (for mTLS)
--key <file>	Specifies the private key file for --cert
--cacert <file>	Uses a custom CA certificate file
--cookie <data>	Sends cookies with the request
--cookie-jar <file>	Stores received cookies into a file
--trace <file>	Logs a full trace of the request/response (headers + body)
--trace-ascii <file>	Logs trace in a human-readable format
--fail	Fails silently on HTTP errors (no body output on 400/500)

Common curl Commands

1. GET Request (default method)

curl https://api.example.com/users

Sends a GET request to fetch data.

2. POST Request with JSON Body

curl -X POST https://api.example.com/users \
  -H "Content-Type: application/json" \
  -d '{"name":"Alice","email":"[e-mail]"}'

• -X specifies the HTTP method (POST)

• -H adds a header

• -d sends data in the request body

3. PUT Request

curl -X PUT https://api.example.com/users/123 \
  -H "Content-Type: application/json" \
  -d '{"email":"[e-mail]"}'

Used to update existing data.

4. DELETE Request

curl -X DELETE https://api.example.com/users/123

Deletes a resource by ID.

5. Custom Headers

curl https://api.example.com/data \
  -H "Authorization: Bearer <token>" \
  -H "Accept: application/json"

Adds headers like auth tokens and Accept types.

6. Form Submission (application/x-www-form-urlencoded)

curl -X POST https://api.example.com/login \
  -d "username=admin&password=secret"

Mimics a form submission.

7. File Upload

curl -X POST https://api.example.com/upload \
  -F "file=@path/to/file.jpg"

Uses multipart/form-data for uploading files.

8. Save Response to File

curl https://example.com/image.jpg -o image.jpg

Downloads and saves the file.

9. View Response Headers

curl -I https://api.example.com

Shows HTTP headers only, without the response body.

10. Verbose Output (for debugging)

curl -v https://api.example.com

Prints detailed request/response information, including headers and connection steps.

11. Basic Authentication

curl -u username:password https://api.example.com/secure

Adds a Authorization: Basic header.

12. Bearer Token Authentication

curl -H "Authorization: Bearer <token>" https://api.example.com

Used for OAuth 2.0 or JWT-secured APIs.