How to Send PATCH Requests with Curl

PATCH requests are HTTP methods used to apply partial modifications to a resource, making them essential for API interactions where you need to update specific fields without replacing the entire resource. Unlike PUT requests that replace the complete resource, PATCH requests allow you to send only the fields you want to modify.

Basic PATCH Request Syntax

The fundamental syntax for sending a PATCH request with curl uses the -X PATCH option to specify the HTTP method:

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

However, most PATCH requests require additional data and headers to be useful in real-world scenarios.

Sending JSON Data with PATCH

The most common use case for PATCH requests involves sending JSON data to update specific fields of a resource. Here's how to structure a complete PATCH request with JSON payload:

curl -X PATCH \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"email": "newemail@example.com", "name": "Updated Name"}' \
  https://api.example.com/users/123

Breaking Down the Command

• -X PATCH: Specifies the HTTP method
• -H "Content-Type: application/json": Tells the server you're sending JSON data
• -H "Accept: application/json": Indicates you expect JSON response
• -d '{"email": "newemail@example.com", "name": "Updated Name"}': The JSON payload containing fields to update

Using Data Files for Complex Payloads

For larger or more complex JSON payloads, it's often better to store the data in a file:

# Create a JSON file
echo '{"profile": {"bio": "Updated bio", "location": "New York"}, "settings": {"notifications": true}}' > update_data.json

# Send PATCH request using the file
curl -X PATCH \
  -H "Content-Type: application/json" \
  -d @update_data.json \
  https://api.example.com/users/123

The @ symbol tells curl to read the data from the specified file.

PATCH with Authentication

Most APIs require authentication for PATCH requests. Here are common authentication methods:

Bearer Token Authentication

curl -X PATCH \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_access_token_here" \
  -d '{"status": "active"}' \
  https://api.example.com/users/123

Basic Authentication

curl -X PATCH \
  -u username:password \
  -H "Content-Type: application/json" \
  -d '{"role": "admin"}' \
  https://api.example.com/users/123

API Key Authentication

curl -X PATCH \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key_here" \
  -d '{"plan": "premium"}' \
  https://api.example.com/users/123

Form Data PATCH Requests

While JSON is most common, some APIs accept form data for PATCH requests:

curl -X PATCH \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "email=newemail@example.com&status=verified" \
  https://api.example.com/users/123

For multipart form data (useful when updating files):

curl -X PATCH \
  -F "avatar=@profile_picture.jpg" \
  -F "bio=Updated user bio" \
  https://api.example.com/users/123

Advanced PATCH Request Examples

Updating Nested JSON Objects

curl -X PATCH \
  -H "Content-Type: application/json" \
  -d '{
    "preferences": {
      "theme": "dark",
      "language": "en-US"
    },
    "contact": {
      "phone": "+1-555-0123"
    }
  }' \
  https://api.example.com/users/123

Array Operations

# Adding items to an array
curl -X PATCH \
  -H "Content-Type: application/json" \
  -d '{"tags": ["developer", "api", "curl"]}' \
  https://api.example.com/posts/456

# Removing specific array elements (API-dependent)
curl -X PATCH \
  -H "Content-Type: application/json" \
  -d '{"remove_tags": ["outdated", "legacy"]}' \
  https://api.example.com/posts/456

Error Handling and Response Inspection

Include response details to debug PATCH requests effectively:

curl -X PATCH \
  -H "Content-Type: application/json" \
  -d '{"email": "invalid-email"}' \
  -w "HTTP Status: %{http_code}\nTotal Time: %{time_total}s\n" \
  -i \
  https://api.example.com/users/123

Options explained: - -w: Writes out specific information after completion - -i: Includes response headers in output - -v: Verbose mode for detailed request/response information

Common PATCH Request Patterns

Conditional Updates with ETags

# Get current resource version
ETAG=$(curl -s -I https://api.example.com/users/123 | grep -i etag | cut -d' ' -f2)

# Update with conditional header
curl -X PATCH \
  -H "Content-Type: application/json" \
  -H "If-Match: $ETAG" \
  -d '{"last_login": "2024-01-15T10:30:00Z"}' \
  https://api.example.com/users/123

Bulk Updates

curl -X PATCH \
  -H "Content-Type: application/json" \
  -d '{
    "users": [
      {"id": 123, "status": "active"},
      {"id": 124, "status": "inactive"},
      {"id": 125, "role": "moderator"}
    ]
  }' \
  https://api.example.com/users/bulk-update

PATCH vs PUT vs POST

Understanding when to use PATCH is crucial:

• PATCH: Partial updates (modify specific fields)
• PUT: Complete resource replacement
• POST: Create new resources or non-idempotent operations

# PATCH - Update only email
curl -X PATCH -H "Content-Type: application/json" \
  -d '{"email": "new@example.com"}' \
  https://api.example.com/users/123

# PUT - Replace entire user resource
curl -X PUT -H "Content-Type: application/json" \
  -d '{"id": 123, "name": "John", "email": "new@example.com", "status": "active"}' \
  https://api.example.com/users/123

Real-World API Examples

GitHub API

# Update repository description
curl -X PATCH \
  -H "Authorization: token your_github_token" \
  -H "Content-Type: application/json" \
  -d '{"description": "Updated repository description"}' \
  https://api.github.com/repos/username/repository

REST API User Profile Update

curl -X PATCH \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_token" \
  -d '{
    "profile": {
      "first_name": "John",
      "last_name": "Doe"
    },
    "preferences": {
      "newsletter": false
    }
  }' \
  https://api.yourservice.com/v1/profile

Troubleshooting PATCH Requests

Common Issues and Solutions

1. 405 Method Not Allowed: The endpoint doesn't support PATCH

# Check allowed methods
curl -X OPTIONS -i https://api.example.com/users/123

1. 415 Unsupported Media Type: Wrong Content-Type header

# Ensure correct Content-Type
curl -X PATCH \
  -H "Content-Type: application/json" \
  # ... rest of command

1. 422 Unprocessable Entity: Invalid data format

# Validate JSON before sending
echo '{"email": "test@example.com"}' | json_pp

Performance and Best Practices

Optimizing PATCH Requests

1. Send only changed fields to minimize payload size
2. Use compression for large payloads:

curl -X PATCH \
  -H "Content-Type: application/json" \
  -H "Content-Encoding: gzip" \
  --compressed \
  -d @large_update.json \
  https://api.example.com/users/123

1. Implement retry logic for critical updates:

# Simple retry wrapper
for i in {1..3}; do
  if curl -X PATCH \
    -H "Content-Type: application/json" \
    -d '{"status": "updated"}' \
    https://api.example.com/users/123; then
    break
  fi
  sleep 2
done

Conclusion

PATCH requests with curl provide a powerful way to update resources partially, making them essential for efficient API interactions. Whether you're updating user profiles, modifying configuration settings, or applying incremental changes to any resource, mastering these curl techniques will significantly improve your API integration workflows.

Remember to always include appropriate headers, handle authentication properly, and validate your JSON payloads before sending PATCH requests. For complex web scraping scenarios that require dynamic content interaction, consider complementing curl with tools that can handle JavaScript-heavy websites effectively.

The key to successful PATCH requests lies in understanding the API's expected data format, using proper authentication, and sending only the fields that need updating rather than the entire resource.