Mastering cURL for API Testing and Documentation

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:

Copycurl https://api.example.com
Copy

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

Adding Request Headers

Headers provide additional information to the API server. Use the -H flag to include headers:

Copycurl -X GET "https://api.example.com" -H "Authorization: Bearer your_token" -H "Accept: application/json"
Copy

Common API Request Headers

Sending Query Parameters

To filter or sort data, include query parameters in your URL:

Copycurl -X GET "https://api.example.com/users?limit=10&sort=desc&status=active"
Copy

Working with Request Data

Sending JSON Data

Use the -d flag to send JSON data in POST, PUT, or PATCH requests:

Copycurl -X POST "https://api.example.com/users" \
     -d '{"name":"John Doe","email":"john@example.com","role":"admin"}' \
     -H "Content-Type: application/json"
Copy

Sending Form Data

For form submissions, use --data-urlencode to properly handle special characters:

Copycurl -X POST "https://api.example.com/login" \
     --data-urlencode "username=johndoe" \
     --data-urlencode "password=s3cure!p@ss"
Copy

Authentication Methods with cURL

File Operations with cURL

Uploading Files

The -F flag allows you to upload files using multipart form data:

Copycurl -X POST "https://api.example.com/upload" \
     -F "file=@/path/to/myfile.jpg" \
     -F "description=My vacation photo" \
     -H "Authorization: Bearer your_token"
Copy

Downloading Files

Save API responses directly to files:

Copy# 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"
Copy

Debugging API Calls

Viewing Response Headers

Use the -i flag to see both the headers and the response body:

Copycurl -i "https://api.example.com/users/1"
Copy

Using Verbose Mode

The -v flag shows the complete request and response flow, perfect for debugging:

Copycurl -v "https://api.example.com/users/1"
Copy

Example output:

Copy> 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"}
Copy

Silent Mode

For scripting, use -s to suppress progress meters and error messages:

Copycurl -s "https://api.example.com/users/1" | jq
Copy

Advanced cURL Features

Practical cURL Examples for API Documentation

1. Fetching resources with authentication

Copycurl -X GET "https://api.example.com/users" \
     -H "Authorization: Bearer your_token" \
     -H "Accept: application/json"
Copy

2. Creating a new resource

Copycurl -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"
     }'
Copy

3. Updating a resource

Copycurl -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"
     }'
Copy

4. Deleting a resource

Copycurl -X DELETE "https://api.example.com/products/123" \
     -H "Authorization: Bearer your_token"
Copy

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

Next Steps

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.