System design · Day 4
API design: define the boundaries of the system
Turn product actions into stable contracts with resources, validation, pagination, idempotency, and useful errors.
An API is a promise between parts of a system. A clear contract lets clients and servers change independently without turning every release into a coordinated event.
Model product actions as resources
Begin with the user journeys from Day 2. For a notes product, resources might be users, notes, and folders. Use predictable operations: POST /notes creates, GET /notes/{id} reads, PATCH changes selected fields, and DELETE removes.
Request and response bodies should be explicit, versionable, and smaller than the internal database model. Validate at the boundary and return errors that identify what failed without leaking implementation details.
Protect list and write operations
Every growing list needs pagination. Cursor pagination remains stable when records are inserted between requests, while offset pagination is simpler for small administrative lists. Include a deterministic sort order so page boundaries are repeatable.
Clients retry when networks fail. For operations such as payment or order creation, accept an idempotency key and return the original result when the same request repeats. This connects API behavior to the failure handling covered on Day 9.
Keep the contract independent
Do not expose table names or require clients to orchestrate internal workflows. The API should describe product capabilities while the service owns storage and coordination. Authentication answers who is calling; authorization decides whether that caller may perform this action.
With a request contract in place, Day 5 can design data around concrete reads and writes. Day 7 will use the same boundary to decide which side effects can happen asynchronously.