The contract comes first
After scope and estimates, sketch the API. It names the operations clients call, their inputs, and their outputs. Defining this contract early forces the requirements to become concrete and gives the rest of the design a clear surface to support.
What to specify
- Endpoints or methods, one per core action.
- Parameters including identifiers, bodies, and pagination.
- Responses with the shape of returned data and status.
- Errors so callers know what failure looks like.
Make it clean
- Match the requirements so every endpoint maps to a feature.
- Paginate lists rather than returning unbounded sets.
- Use stable identifiers so clients can cache and retry.
- Keep writes idempotent where possible for safe retries.
Why it helps the flow
A clear API anchors the conversation. When you later draw services and databases, each one exists to serve an endpoint. It also surfaces hidden requirements, like whether a feed is pulled by the client or pushed by the server.
Key idea
Design the API contract early so each endpoint maps to a requirement and the internal architecture has a concrete surface to serve.