How do I use Curl to send PUT requests?

PUT requests are essential for updating resources in RESTful APIs and web services. Curl provides powerful options for sending PUT requests with various types of data, headers, and authentication methods. This comprehensive guide covers everything you need to know about using Curl for PUT operations.

Basic PUT Request Syntax

The fundamental syntax for sending a PUT request with Curl uses the -X PUT or --request PUT option:

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

This sends an empty PUT request to the specified endpoint. However, PUT requests typically include data to update the resource.

Sending JSON Data with PUT Requests

Most modern APIs expect JSON data in PUT requests. Use the -d or --data option along with the appropriate Content-Type header:

curl -X PUT \
  -H "Content-Type: application/json" \
  -d '{"name": "John Doe", "email": "john@example.com"}' \
  https://api.example.com/users/123

For better readability with complex JSON, you can use a here document:

curl -X PUT \
  -H "Content-Type: application/json" \
  -d @- \
  https://api.example.com/users/123 << 'EOF'
{
  "name": "John Doe",
  "email": "john@example.com",
  "profile": {
    "age": 30,
    "location": "New York"
  }
}
EOF

Sending Data from Files

When working with large payloads or when you want to keep your data separate from the command, you can read data from files:

# Send JSON data from a file
curl -X PUT \
  -H "Content-Type: application/json" \
  -d @user_data.json \
  https://api.example.com/users/123

# Send form data from a file
curl -X PUT \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d @form_data.txt \
  https://api.example.com/users/123

Form Data in PUT Requests

To send form-encoded data, use the appropriate Content-Type header:

curl -X PUT \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "name=John+Doe&email=john@example.com&age=30" \
  https://api.example.com/users/123

Alternatively, you can let Curl automatically encode the data:

curl -X PUT \
  --data-urlencode "name=John Doe" \
  --data-urlencode "email=john@example.com" \
  --data-urlencode "age=30" \
  https://api.example.com/users/123

File Uploads with PUT Requests

PUT requests are commonly used for uploading or updating files. Here are several approaches:

Binary File Upload

# Upload a binary file
curl -X PUT \
  -H "Content-Type: application/octet-stream" \
  --data-binary @image.jpg \
  https://api.example.com/files/123

# Upload with specific content type
curl -X PUT \
  -H "Content-Type: image/jpeg" \
  --data-binary @profile.jpg \
  https://api.example.com/users/123/avatar

Multipart File Upload

curl -X PUT \
  -F "file=@document.pdf" \
  -F "description=Updated document" \
  https://api.example.com/documents/123

Authentication in PUT Requests

Basic Authentication

curl -X PUT \
  -u username:password \
  -H "Content-Type: application/json" \
  -d '{"name": "Updated Name"}' \
  https://api.example.com/users/123

Bearer Token Authentication

curl -X PUT \
  -H "Authorization: Bearer your_token_here" \
  -H "Content-Type: application/json" \
  -d '{"name": "Updated Name"}' \
  https://api.example.com/users/123

API Key Authentication

curl -X PUT \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"name": "Updated Name"}' \
  https://api.example.com/users/123

Advanced PUT Request Options

Custom Headers

Add multiple custom headers to your PUT requests:

curl -X PUT \
  -H "Content-Type: application/json" \
  -H "X-Request-ID: 12345" \
  -H "User-Agent: MyApp/1.0" \
  -H "Accept: application/json" \
  -d '{"status": "active"}' \
  https://api.example.com/users/123

Handling Response Data

Save the response to a file and include response headers:

curl -X PUT \
  -H "Content-Type: application/json" \
  -d '{"name": "Updated Name"}' \
  -o response.json \
  -D headers.txt \
  https://api.example.com/users/123

Verbose Output for Debugging

Use the -v flag to see detailed request and response information:

curl -X PUT \
  -v \
  -H "Content-Type: application/json" \
  -d '{"name": "Debug Test"}' \
  https://api.example.com/users/123

Error Handling and Status Codes

Check HTTP status codes and handle errors appropriately:

# Write HTTP status code to a file
curl -X PUT \
  -H "Content-Type: application/json" \
  -d '{"name": "Test"}' \
  -w "%{http_code}" \
  -o response.json \
  https://api.example.com/users/123

# Fail silently on HTTP errors
curl -X PUT \
  -f \
  -H "Content-Type: application/json" \
  -d '{"name": "Test"}' \
  https://api.example.com/users/123

PUT vs PATCH: When to Use Each

Understanding the difference between PUT and PATCH is crucial:

PUT: Replaces the entire resource. Send all fields, even unchanged ones.
PATCH: Partially updates a resource. Send only the fields you want to change.

# PUT - Complete resource replacement
curl -X PUT \
  -H "Content-Type: application/json" \
  -d '{"name": "John", "email": "john@example.com", "age": 30}' \
  https://api.example.com/users/123

# PATCH - Partial update (if supported)
curl -X PATCH \
  -H "Content-Type: application/json" \
  -d '{"age": 31}' \
  https://api.example.com/users/123

Common PUT Request Patterns

Idempotent Updates

PUT requests should be idempotent, meaning multiple identical requests should have the same effect:

# This request can be safely repeated
curl -X PUT \
  -H "Content-Type: application/json" \
  -d '{"name": "John Doe", "status": "active"}' \
  https://api.example.com/users/123

Conditional Updates

Use ETags or version numbers for conditional updates:

curl -X PUT \
  -H "Content-Type: application/json" \
  -H "If-Match: \"etag-value-here\"" \
  -d '{"name": "Updated Name"}' \
  https://api.example.com/users/123

Integration with Web Scraping Workflows

PUT requests are often part of larger web scraping and data processing workflows. After extracting data with tools like how to handle authentication in Puppeteer, you might need to update APIs with the scraped information.

For complex scenarios involving dynamic content updates, you might combine Curl PUT requests with browser automation tools to handle AJAX requests using Puppeteer for comprehensive data management.

Troubleshooting Common Issues

Content-Length Issues

Curl automatically calculates Content-Length, but you can set it manually if needed:

curl -X PUT \
  -H "Content-Type: application/json" \
  -H "Content-Length: 45" \
  -d '{"name": "John", "email": "john@example.com"}' \
  https://api.example.com/users/123

SSL Certificate Problems

For development environments with self-signed certificates:

curl -X PUT \
  -k \
  -H "Content-Type: application/json" \
  -d '{"name": "Test"}' \
  https://localhost:8443/api/users/123

Timeout Configuration

Set appropriate timeouts for long-running PUT operations:

curl -X PUT \
  --connect-timeout 30 \
  --max-time 300 \
  -H "Content-Type: application/json" \
  -d @large_data.json \
  https://api.example.com/users/123

Programming Language Examples

Python with subprocess

import subprocess
import json

def send_put_request(url, data):
    json_data = json.dumps(data)
    cmd = [
        'curl', '-X', 'PUT',
        '-H', 'Content-Type: application/json',
        '-d', json_data,
        url
    ]

    result = subprocess.run(cmd, capture_output=True, text=True)
    return result.stdout, result.returncode

# Usage
data = {"name": "John Doe", "email": "john@example.com"}
response, status = send_put_request("https://api.example.com/users/123", data)

JavaScript with child_process

const { exec } = require('child_process');

function sendPutRequest(url, data) {
    const jsonData = JSON.stringify(data);
    const cmd = `curl -X PUT -H "Content-Type: application/json" -d '${jsonData}' ${url}`;

    return new Promise((resolve, reject) => {
        exec(cmd, (error, stdout, stderr) => {
            if (error) {
                reject(error);
                return;
            }
            resolve(stdout);
        });
    });
}

// Usage
const data = { name: "John Doe", email: "john@example.com" };
sendPutRequest("https://api.example.com/users/123", data)
    .then(response => console.log(response))
    .catch(error => console.error(error));

Best Practices

Always specify Content-Type: Include the appropriate Content-Type header for your data format.
Use meaningful HTTP status codes: Expect and handle 200 (OK), 204 (No Content), 404 (Not Found), and 409 (Conflict) responses.
Implement proper error handling: Check HTTP status codes and response content for errors.
Test with verbose output: Use -v flag during development to understand request/response flow.
Secure sensitive data: Never include credentials directly in command history; use environment variables or configuration files.
Validate data format: Ensure your JSON is properly formatted before sending.
Handle large payloads: Use file input for large data sets to avoid command line limitations.

PUT requests with Curl are powerful tools for API interactions and data updates. By understanding these patterns and options, you can effectively integrate PUT operations into your web scraping and API automation workflows.

Table of contents