api-design

Start by identifying the resource and its lifecycle, then express actions through HTTP methods rather than path names. Define request validation, success responses, and error responses, and only add pagination, filtering, or sorting when the endpoint actually needs them.

Add pagination, filtering, and sorting only when the endpoint's data volume or use cases require them. Decide the behavior upfront and document it so consumers can rely on consistent response shapes.

Introduce versioning only when there is a real compatibility need, such as a breaking change to existing wire behavior. Document compatibility constraints before changing any existing endpoint behavior.

Prefer partial updates only when patch semantics are clear and documented. Ambiguous partial update behavior leads to inconsistent state, so define how omitted fields and defaults are handled before exposing the endpoint.

Common mistakes include action-heavy URLs instead of resource naming, inventing versioning without need, and adding optional fields without stating defaults and omission behavior. Keeping response and error shapes consistent avoids most consumer-facing issues.