Bulk & Async Operations

Real APIs sometimes need to change many resources at once, or kick off work that takes longer than a request should wait. Both stretch the simple one-request-one-resource model, so they need deliberate design.

Bulk operations

To act on many items in one call, POST to a batch endpoint with a list, and return a per-item result so callers learn exactly what succeeded:

POST /articles/batch HTTP/1.1
Content-Type: application/json

{ "items": [ { "title": "A" }, { "title": "" } ] }

The response reports each item’s outcome rather than a single overall status — partial success is the norm for batches:

JavaScript

function processBatch(items) {
  return items.map((item, i) => {
    if (!item.title) {
      return { index: i, status: 422, error: 'title is required' };
    }
    return { index: i, status: 201, id: 1000 + i };
  });
}

const results = processBatch([{ title: 'A' }, { title: '' }, { title: 'C' }]);
console.log(JSON.stringify(results, null, 2));
const ok = results.filter((r) => r.status < 400).length;
console.log(ok + '/' + results.length + ' succeeded');

Long-running (async) work

When an operation cannot finish within a request (a big export, a video transcode), do not hold the connection open. Accept the work and return 202 Accepted with a link to a status resource the client can poll:

sequenceDiagram
  participant C as Client
  participant S as API
  C->>S: POST /exports
  S-->>C: 202 Accepted + Location: /exports/job-1
  C->>S: GET /exports/job-1
  S-->>C: 200 OK { status: "running" }
  C->>S: GET /exports/job-1
  S-->>C: 200 OK { status: "done", result: "/files/x" }

202 Accepted plus a pollable status resource

The job itself becomes a resource: POST /exports creates it, GET /exports/{id} reports progress, and the final response links to the produced result.