Mastering cURL for API Testing and Documentation
Learn how to use cURL to test API endpoints, authenticate requests, send data payloads, and debug responses. Essential command line techniques for technical writers and developers working with REST APIs.
Table of Contents
You’ve already tackled API fundamentals—rate limits, authentication, pagination, and error handling. Now, it’s time to level up and master cURL, the command-line Swiss Army knife for API testing.
What You’ll Learn in This Chapter
After completing this chapter, you’ll be able to:
- Execute API requests using various HTTP methods (GET, POST, PUT, DELETE)
- Include headers and authentication tokens in your requests
- Send data payloads in JSON and form-encoded formats
- Upload and download files through API endpoints
- Debug API responses using cURL’s powerful features
- Troubleshoot common API issues directly from the command line
Let’s get started with the essentials!
What is cURL?
cURL (short for Client URL) is a command-line tool used for sending HTTP requests to APIs. It’s like Postman, but without the fancy UI.
A basic cURL command looks like this:
curl https://api.example.com
This sends a GET request to https://api.example.com
. Simple, right? Now, let’s explore more powerful features.
Sending API Requests with cURL
HTTP Methods and cURL Commands
HTTP Method | cURL Command | Purpose | Example Use Case |
---|---|---|---|
GET | curl -X GET "https://api.example.com/users" |
Retrieve data | Fetch user profiles, product listings |
POST | curl -X POST "https://api.example.com/users" -d '{"name":"John"}' -H "Content-Type: application/json" |
Create new data | Create new user, submit form data |
PUT | curl -X PUT "https://api.example.com/users/1" -d '{"name":"John Updated"}' -H "Content-Type: application/json" |
Update existing data | Update user profile, replace a resource |
DELETE | curl -X DELETE "https://api.example.com/users/1" |
Remove data | Delete a user account, remove a post |
PATCH | curl -X PATCH "https://api.example.com/users/1" -d '{"status":"active"}' -H "Content-Type: application/json" |
Partially update data | Update specific fields only |
Adding Request Headers
Headers provide additional information to the API server. Use the -H
flag to include headers:
curl -X GET "https://api.example.com" -H "Authorization: Bearer your_token" -H "Accept: application/json"
Common API Request Headers
Header | Purpose | Example |
---|---|---|
Authorization | Authenticate requests | -H "Authorization: Bearer token123" |
Content-Type | Specify request body format | -H "Content-Type: application/json" |
Accept | Specify desired response format | -H "Accept: application/json" |
User-Agent | Identify client application | -H "User-Agent: MyApiClient/1.0" |
Sending Query Parameters
To filter or sort data, include query parameters in your URL:
curl -X GET "https://api.example.com/users?limit=10&sort=desc&status=active"
Working with Request Data
Sending JSON Data
Use the -d
flag to send JSON data in POST, PUT, or PATCH requests:
curl -X POST "https://api.example.com/users" \
-d '{"name":"John Doe","email":"john@example.com","role":"admin"}' \
-H "Content-Type: application/json"
Sending Form Data
For form submissions, use --data-urlencode
to properly handle special characters:
curl -X POST "https://api.example.com/login" \
--data-urlencode "username=johndoe" \
--data-urlencode "password=s3cure!p@ss"
Authentication Methods with cURL
Authentication Type | cURL Command | When to Use |
---|---|---|
API Key | curl -H "Authorization: ApiKey your_api_key" "https://api.example.com" |
Simple API authentication |
Bearer Token | curl -H "Authorization: Bearer your_token" "https://api.example.com" |
OAuth or JWT authentication |
Basic Auth | curl -u username:password "https://api.example.com" |
Username/password authentication |
OAuth 2.0 | curl -H "Authorization: Bearer oauth_token" "https://api.example.com" |
Third-party API access |
File Operations with cURL
Uploading Files
The -F
flag allows you to upload files using multipart form data:
curl -X POST "https://api.example.com/upload" \
-F "file=@/path/to/myfile.jpg" \
-F "description=My vacation photo" \
-H "Authorization: Bearer your_token"
Downloading Files
Save API responses directly to files:
# Save with original filename
curl -O "https://api.example.com/files/document.pdf"
# Save with custom filename
curl -o custom_name.pdf "https://api.example.com/files/document.pdf"
Debugging API Calls
Viewing Response Headers
Use the -i
flag to see both the headers and the response body:
curl -i "https://api.example.com/users/1"
Using Verbose Mode
The -v
flag shows the complete request and response flow, perfect for debugging:
curl -v "https://api.example.com/users/1"
Example output:
> GET /users/1 HTTP/1.1
> Host: api.example.com
> User-Agent: curl/7.68.0
> Accept: */*
>
< HTTP/1.1 200 OK
< Content-Type: application/json
< Content-Length: 234
<
{"id":1,"name":"John Doe","email":"john@example.com"}
Silent Mode
For scripting, use -s
to suppress progress meters and error messages:
curl -s "https://api.example.com/users/1" | jq
Advanced cURL Features
Feature | Flag | Example | Purpose |
---|---|---|---|
Follow Redirects | -L |
curl -L "https://api.example.com/redirect" |
Automatically follow HTTP redirects |
Request Timeout | --connect-timeout |
curl --connect-timeout 10 "https://api.example.com" |
Set connection timeout in seconds |
Max Time | --max-time |
curl --max-time 30 "https://api.example.com" |
Set maximum time allowed for operation |
Retry Requests | --retry |
curl --retry 3 "https://api.example.com" |
Retry failed requests |
Custom Request Method | -X |
curl -X PATCH "https://api.example.com" |
Use specific HTTP method |
Practical cURL Examples for API Documentation
1. Fetching resources with authentication
curl -X GET "https://api.example.com/users" \
-H "Authorization: Bearer your_token" \
-H "Accept: application/json"
2. Creating a new resource
curl -X POST "https://api.example.com/products" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer your_token" \
-d '{
"name": "New Product",
"price": 29.99,
"description": "This is a new product",
"category": "electronics"
}'
3. Updating a resource
curl -X PUT "https://api.example.com/products/123" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer your_token" \
-d '{
"name": "Updated Product Name",
"price": 39.99,
"description": "This product has been updated",
"category": "electronics"
}'
4. Deleting a resource
curl -X DELETE "https://api.example.com/products/123" \
-H "Authorization: Bearer your_token"
Putting It All Together
cURL is an incredibly powerful tool for:
- Testing APIs before implementing them in code
- Documenting API endpoints with clear examples
- Debugging API issues with detailed request/response information
- Automating API workflows with shell scripts
- Validating API responses against expected results
Key Takeaways
- cURL allows you to interact with APIs directly from the command line
- Use different HTTP methods with the -X flag (GET, POST, PUT, DELETE, PATCH)
- Add request headers with -H for authentication and content type specification
- Send data payloads with -d for JSON or --data-urlencode for form data
- Upload files using -F and download using -O or -o
- Debug API calls using the -v (verbose) and -i (include headers) flags
Test Your cURL Knowledge
What cURL command would you use to send a POST request with JSON data and include the response headers in the output?
Frequently Asked Questions About cURL for API Testing
Get answers to common questions about using cURL for API testing and documentation.
cURL Basics
cURL (Client URL) is a command-line tool for making HTTP requests to APIs. It’s useful for API testing because it allows you to test endpoints without writing code, works on almost all operating systems, and provides powerful debugging capabilities through the command line.
cURL comes pre-installed on most macOS and Linux systems. For Windows, you can download it from the official website (curl.se) or install it via package managers like Chocolatey (choco install curl) or Windows Subsystem for Linux. Verify installation by typing ‘curl –version’ in your terminal.
While both are command-line tools for HTTP requests, cURL supports more protocols beyond HTTP/HTTPS, offers better support for APIs with various authentication methods, and focuses on data transfer. wget is primarily designed for downloading files and websites, with better recursive downloading capabilities.
Break long commands into multiple lines using the backslash character () at the end of each line. Use indentation for clarity, especially for multiple headers or data fields. You can also save frequently used commands in shell scripts for reuse.
Making Requests with cURL
Use the -X flag followed by the HTTP method: ‘curl -X GET url’ for GET, ‘curl -X POST url’ for POST, ‘curl -X PUT url’ for PUT, ‘curl -X DELETE url’ for DELETE, and ‘curl -X PATCH url’ for PATCH requests. GET is the default method if -X is not specified.
Use the -H flag followed by the header name and value: ‘curl -H “Content-Type: application/json” -H “Authorization: Bearer token123” url’. You can add multiple headers by using multiple -H flags.
Add query parameters directly to the URL: ‘curl https://api.example.com/users?limit=10&sort=desc’. For parameters with special characters, you can use URL encoding or place the URL in quotes.
Use the -i flag to include response headers: ‘curl -i https://api.example.com’. For even more detail, use -v (verbose mode) which shows the complete request and response including headers: ‘curl -v https://api.example.com’.
Working with Data
Use the -d flag followed by your JSON data in quotes: ‘curl -X POST https://api.example.com -d ‘{“name”:”John”,”email”:”john@example.com”}’ -H “Content-Type: application/json”’. For complex JSON, consider storing it in a file and using -d @filename.json.
Use –data-urlencode to properly handle special characters in form fields: ‘curl -X POST https://api.example.com/login –data-urlencode “username=john” –data-urlencode “password=s3cur3!”’. Multiple fields are automatically formatted correctly.
Use the -F flag for form-based file uploads: ‘curl -X POST https://api.example.com/upload -F “file=@/path/to/file.pdf” -F “description=My Document”’. The @ symbol indicates a file path rather than literal text.
Use curl with the -o flag to specify the output filename: ‘curl -o filename.pdf https://api.example.com/files/download’. For large files, add –progress-bar to see download progress: ‘curl –progress-bar -o filename.pdf url’.
Authentication with cURL
Use the -u flag followed by username:password: ‘curl -u username:password https://api.example.com’. For security, you can omit the password and cURL will prompt you to enter it: ‘curl -u username https://api.example.com’.
Add them as headers: ‘curl -H “Authorization: Bearer your_token” https://api.example.com’ for Bearer tokens, or ‘curl -H “X-API-Key: your_api_key” https://api.example.com’ for API keys. Some APIs might require them as query parameters instead.
First obtain an access token from the authorization server, then include it in your requests as a Bearer token: ‘curl -H “Authorization: Bearer your_oauth_token” https://api.example.com’. The token acquisition process varies by provider and may require multiple cURL commands.
Use –cookie-jar to save cookies: ‘curl –cookie-jar cookies.txt https://api.example.com/login -d “username=user&password=pass”’. Then use –cookie to use those cookies in subsequent requests: ‘curl –cookie cookies.txt https://api.example.com/profile’.
Debugging and Troubleshooting
Use -v (verbose) flag to see detailed request and response information: ‘curl -v https://api.example.com’. For even more details, use -vv or -vvv. To focus only on headers, use -I for just response headers: ‘curl -I https://api.example.com’.
Use the -L flag to follow redirects: ‘curl -L https://api.example.com’. This is useful when APIs redirect to authentication services or when dealing with URL shorteners. You can limit the number of redirects with –max-redirs: ‘curl -L –max-redirs 5 url’.
Use the -w (write-out) flag with timing variables: ‘curl -w “\nTotal time: %{time_total}s\n” https://api.example.com’. This helps identify performance issues. For a complete timing breakdown, try ‘curl -w “@curl-format.txt” url’ with a custom format file.
Use the -o flag for saving to a specific file: ‘curl -o response.json https://api.example.com’. To save with the same name as the remote file, use -O: ‘curl -O https://example.com/file.zip’. For only saving on successful responses, add the –fail option.
Congratulations! You’re now fluent in cURL, ready to test APIs like a pro. You’re fully prepared for intermediate and advanced-level API documentation challenges.
In the next chapter, we’ll put your skills to the test with expert REST API exercises that combine everything you’ve learned so far.
Test Your Knowledge
API Testing Resources
Explore more tools and resources for API testing and documentation.