24 Bulk Operations

title: Bulk Operations in REST API Design — Complete Guide weight: 34 date: 2026-06-28 lastmod: 2026-06-28 description: Learn bulk operations in REST APIs for creating, updating, and deleting multiple resources in a single request with atomicity, error handling, and performance patterns. tags: [api-development, rest]

Bulk operations in REST APIs allow creating, updating, or deleting multiple resources in a single request, reducing network overhead and improving throughput for batch data processing scenarios.

```mermaid
flowchart TD
  A[Bulk Operations] --> B[Bulk Create]
  A --> C[Bulk Update]
  A --> D[Bulk Delete]
  B --> E[POST /users/batch]
  C --> F[PATCH /users/batch]
  D --> G[DELETE /users/batch]
  E --> H[201 + Created IDs]
  F --> I[200 + Updated IDs]
  G --> J[204]
  style A fill:#e1f5fe
  style B fill:#c8e6c9
  style F fill:#c8e6c9

Bulk endpoints accept arrays of resources instead of single objects. A bulk create sends [user1, user2, user3] to POST /users/batch and returns the created resources. Responses must handle partial failures where some operations succeed and others fail.

Think of bulk operations like a shopping list. Instead of going to the store once for each item (individual API calls), you go once with your entire list (bulk call). If one item is out of stock (partial failure), you still get the rest.

Example: Bulk Create

import requests

users = [
    {"name": "Alice", "email": "alice@example.com"},
    {"name": "Bob", "email": "bob@example.com"},
    {"name": "Charlie", "email": "charlie@example.com"}
]
response = requests.post(
    "https://api.example.com/users/batch",
    json={"users": users}
)
result = response.json()
print(f"Created: {result['success_count']} users")
print(f"Failed: {result['error_count']}")
for created in result['created']:
    print(f"  {created['id']}: {created['name']}")

Expected output:

Created: 3 users
Failed: 0
  101: Alice
  102: Bob
  103: Charlie

Example: Bulk Update with Partial Failures

import requests

updates = [
    {"id": 42, "name": "Alice Updated"},
    {"id": 55, "name": "Bob Updated"},
    {"id": 999, "name": "NonExistent"}  # This will fail
]
response = requests.patch(
    "https://api.example.com/users/batch",
    json={"updates": updates}
)
result = response.json()
print(f"Succeeded: {len(result['succeeded'])}")
print(f"Failed: {len(result['failed'])}")
for failure in result['failed']:
    print(f"  ID {failure['id']}: {failure['error']}")

Expected output:

Succeeded: 2
Failed: 1
  ID 999: User not found

Example: Bulk Delete with Filters

import requests

# Bulk delete inactive users
response = requests.delete(
    "https://api.example.com/users/batch",
    json={"filters": {"status": "inactive", "last_login_before": "2025-01-01"}}
)
result = response.json()
print(f"Deleted: {result['deleted_count']} users")
print(f"Not found: {result['not_found_count']}")

Expected output:

Deleted: 12 users
Not found: 0

Common Mistakes

1. Not handling partial failures — When bulk operations fail partially, return success and failure arrays so clients know which items need attention.
2. Ignoring bulk request size limits — Accepting unlimited batch sizes causes memory and timeout issues. Limit batches to 100-1000 items depending on resource complexity.
3. Not making bulk operations atomic when needed — Some use cases require all-or-nothing behavior. Document whether your bulk endpoints are atomic or best-effort.
4. Using the same endpoint for single and bulk operations — Separate bulk endpoints (/users/batch) from single-resource endpoints (/users) to keep code clean and maintainable.
5. Missing validation in bulk operations — Validate every item in the batch with the same rigor as individual requests. Return per-item error details.

Practice Questions

1. When should you use bulk operations instead of individual requests?
2. How do you handle partial failures in bulk operations?
3. What are the security considerations for bulk delete operations?
4. How do you determine a reasonable batch size limit?
5. Challenge: Implement a bulk operation handler in Python that accepts an array of create/update/delete operations, processes them in a transaction, and returns per-item success/failure results with appropriate status codes.

FAQ

Mini Project

Build a Python bulk operation handler class that supports batch create, update, and delete for a resource. The handler should validate each item, process in a configurable batch size, return per-item results with success/failure details, and support both atomic and best-effort modes.

What's Next

Now learn about async operations in REST API Design.