advanced-patterns

Know When to Break the REST Rules

Standard REST with JSON covers most API needs. But some problems -- bulk data import, real-time streaming, multi-tenant isolation, high read:write asymmetry -- demand patterns that go beyond basic CRUD. Reach for these when standard REST creates friction, not before.

Bulk and Batch Operations

When clients need to create, update, or delete many resources at once, individual requests are wasteful. Batch endpoints eliminate the round-trip overhead.

Use the simple batch pattern for homogeneous operations:

Send an array of resources to a dedicated /batch endpoint. Cap batch size at 100 items per request to keep response times predictable and memory usage bounded. Return per-item status with an index for correlation -- never silently drop failures.

Design for partial success, not all-or-nothing:

Approach	When to Use	HTTP Status
Atomic (all-or-nothing)	Financial transactions, consistency-critical operations	200 or 400/422 (all rolled back)
Partial success	Import operations, bulk updates with independent items	200 with per-item status
Async processing	Large batches (1,000+ items)	202 Accepted, poll for results

Every batch response must include a summary object with total, succeeded, and failed counts. For failed items, return the original index and a structured error so the caller knows exactly what to retry.

Switch to async for large batches:

Return 202 Accepted with a Location header pointing to a status resource. The client polls that resource for progress updates. Include estimated_completion when possible. Provide a separate errors endpoint for downloading failures as JSON or CSV. This is the pattern Shopify uses for bulk mutations and Stripe uses for bulk payouts.

REST vs GraphQL vs gRPC vs tRPC

Pick the protocol that matches the consumer, not the one that sounds most modern.

Aspect	REST	GraphQL	gRPC	tRPC
Latency	Good	Good	Excellent (binary, HTTP/2)	Good
Caching	Excellent (HTTP-native)	Hard (POST, single endpoint)	Custom solution required	Custom solution required
Tooling	Mature, abundant	Strong (Apollo, Relay)	Strong (protoc, buf)	TypeScript-native
Learning curve	Low	Medium	Medium-High	Low (TypeScript only)
Browser support	Native	Native (fetch/POST)	Requires grpc-web proxy	Native
Type safety	Via codegen from OpenAPI	Via codegen from SDL	Native (protobuf)	Native (TS inference)
Best for	Public APIs, broad ecosystem	Flexible frontend data needs	Service-to-service	Full-stack TS monorepos