依据JsonAPI规范，为何禁止批量更新？求实例及原因详解

Great question! Let’s dive into why JSON API explicitly prohibits batch updates, walking through concrete examples and the core design decisions behind this rule.

The JSON API specification is built around principles of consistency, predictability, and reliability—batch updates conflict with all three. Let’s break this down with examples and reasoning:

1. Atomicity & Data Consistency Risks #

One of the biggest issues with batch updates is ensuring atomicity: if you try to update multiple resources in a single request, partial failures create inconsistent system states.

Example of a Non-Compliant Batch Update #

This is what a forbidden batch update request might look like:

PATCH /users
{
  "data": [
    {
      "type": "users",
      "id": "1",
      "attributes": { "email": "alice.new@example.com" }
    },
    {
      "type": "users",
      "id": "2",
      "attributes": { "email": "bob.invalid-email" }
    }
  ]
}

In this case, Alice’s email update might succeed, but Bob’s fails because of an invalid email format. Now your database has one updated user and one unchanged—how does the client roll back Alice’s change? JSON API avoids this mess by requiring one resource update per request.

Compliant Alternative (Separate Requests) #

Instead, you’d send two distinct PATCH requests, each targeting a single resource:

// Request 1: Update Alice's email
PATCH /users/1
{
  "data": {
    "type": "users",
    "id": "1",
    "attributes": { "email": "alice.new@example.com" }
  }
}

// Request 2: Update Bob's email (will fail clearly)
PATCH /users/2
{
  "data": {
    "type": "users",
    "id": "2",
    "attributes": { "email": "bob.invalid-email" }
  }
}

Each request is atomic: either it fully succeeds (200 OK with the updated resource) or fully fails (422 Unprocessable Entity with error details), leaving your system in a consistent state.

2. Simplified, Predictable Responses #

JSON API defines a strict response format for every request. Batch updates would force servers to return complex partial success responses (e.g., some resources updated, others failed), which adds unnecessary complexity to both server implementations and client error handling.

By sticking to single-resource updates, clients always know what to expect: a clean success or a detailed error report tied directly to the specific resource being modified. No guessing about which parts of the batch worked or failed.

3. Alignment with REST Principles #

JSON API is deeply rooted in RESTful design, which emphasizes addressing individual resources as distinct entities. Batch operations blur resource boundaries and can lead to non-idempotent behavior—if a batch request is retried (e.g., due to a network glitch), some operations might execute twice while others don’t, causing unintended side effects (like duplicate email updates).

Single-resource requests are inherently idempotent (sending the same request multiple times has the same effect as sending it once), which aligns with REST’s focus on safe, repeatable operations.

4. Improved Debuggability & Intent Clarity #

When every request targets one resource, it’s crystal clear what change is being made. Debugging issues becomes straightforward: you can trace exactly which resource update failed, why, and fix it quickly.

Batch updates, by contrast, obscure intent—if a batch fails, you have to parse through multiple operations to find the culprit. This slows down debugging and increases the chance of misdiagnosing issues.

A quick note: While the core JSON API spec prohibits batch updates, some third-party implementations offer non-standard extensions for bulk operations. However, these bypass the spec’s built-in safeguards and should be used cautiously if at all.

内容的提问来源于stack exchange，提问作者Binh Le