Batch Operations and Custom Actions

Pure REST struggles to express non-CRUD operations like "send invoice", "archive all read notifications", or "merge two accounts". The accepted convention is to model these as sub-resources or action endpoints using POST, keeping the URL noun-based where possible. Batch operations reduce round trips. A PATCH request to a collection endpoint can update multiple records atomically. JSON Patch (RFC 6902) formalises a patch document format—an array of operations (add, remove, replace, move, copy, test)—that can be applied to any JSON document.

Example

# Custom actions as sub-resources (POST)
POST /invoices/88/send          # send invoice by email
POST /orders/55/cancel          # cancel an order
POST /users/42/password-reset   # trigger password reset
POST /notifications/mark-all-read

# Bulk operations
PATCH /products HTTP/1.1
Content-Type: application/json
{
  "ids": [1, 2, 3],
  "update": { "status": "archived" }
}
# Response: 200 OK
# { "updated": 3 }

# JSON Patch (RFC 6902) — fine-grained patch document
PATCH /users/42 HTTP/1.1
Content-Type: application/json-patch+json
[
  { "op": "replace", "path": "/email",      "value": "new@example.com" },
  { "op": "add",     "path": "/tags/-",     "value": "premium" },
  { "op": "remove",  "path": "/legacyField" },
  { "op": "test",    "path": "/version",    "value": 3 }
]
# "test" op: if /version != 3, the entire patch is rejected (optimistic locking)
# Response: 200 OK + updated user, or 409 Conflict if test fails

HTML

Full Editor

Related Resources

REST API Reference

Complete tag & property list

REST API How-To Guides

Step-by-step practical guides

REST API Exercises

Practice what you've learned