REST Design
Resources, uniform methods, status codes and statelessness.
4 to work through
-
intermediate
A developer platform's REST API returns collections that can contain millions of items. Which design decisions separate an API that scales from one that does not?
2 min answer -
intermediate
Which REST API design decisions are expensive to change once consumers exist?
1 min answer -
advanced
A new platform must serve a public partner API, three internal front-ends with different data needs, and high-volume service-to-service traffic. Choose the API styles and defend the choice.
2 min answer -
advanced
A partner integration issues PATCH requests with JSON Merge Patch semantics. On Tuesday one partner's nightly sync cleared the phone number on 40,000 customer records. The requests were valid, your service applied them correctly, and no error was returned anywhere. What happened, and what do you change?
3 min answer
3 terms in this topic
Bulk and Batch API Design
Endpoints that accept many items in one call, and the partial-failure semantics that make them either useful or dangerous.
conceptHTTP Method Semantics
The safety, idempotency and cacheability guarantees each HTTP method carries, which clients and intermediaries rely on.
practiceResource Modelling
Expressing an API as nouns with a consistent hierarchy rather than as verbs, so URLs are predictable and methods carry the semantics.
Neighbouring topics
API & Integration
General material on integrating systems through contracts.
GraphQL
Client-specified queries, N+1 resolution and query-cost control.
gRPC APIs
Contract-first RPC, generated clients and protobuf compatibility rules.
Webhooks
Push callbacks, signature verification, ordering and at-least-once delivery.
API Versioning
URL, header and account-pinned versioning, and who carries the burden.
Backward Compatibility
Which changes are safe, and how to make breakage a build failure.
Contract Testing
Verifying what consumers actually rely on, without a shared environment.
API Documentation
OpenAPI as a machine-checked contract rather than as prose.
Rate Limiting
Algorithms, shared counters, and signalling rejection properly.
Idempotency Keys
Client-generated keys stored atomically with the operation they guard.
Pagination & Filtering
Offset versus cursor, stable ordering and unbounded result sets.
API Error Handling
Error shapes, retryability signals and machine-readable causes.
Event-Driven Integration
Publishing facts rather than commands, and versioning event schemas.
Message Formats
JSON, Protobuf, Avro — schema evolution and payload economics.
Schema Registry
Enforcing compatibility on events the way CI enforces it on code.
Integration Patterns
Routers, translators, splitters, aggregators and dead letter channels.
Legacy Integration
Reaching systems that cannot change, without importing their model.
Partner & B2B Integration
External contracts, onboarding, sandboxes and long deprecation windows.
APIs as Products
Ownership, lifecycle, deprecation policy and developer experience.