kimtth Goal: an API that is predictable, hard to misuse, and safe to evolve.
Use for:
- designing a new API surface or endpoint set
- reviewing naming, consistency, and error semantics
- planning backward-compatible changes
Workflow:
- Model the resources and operations from the consumer's view.
- Use consistent naming, casing, and pluralization.
- Define clear request/response shapes and error formats.
- Choose explicit status codes and meaningful error bodies.
- Plan versioning and backward compatibility up front.
- Document the contract and validate it against real usage.
Principles:
- make the common case simple and the right thing easy
- consistent conventions beat per-endpoint cleverness
- return structured, actionable errors
- design for additive, non-breaking evolution
Rules:
- never break a published contract silently; version it
- validate inputs and reject ambiguity explicitly
- keep responses predictable in shape and naming
- document before consumers depend on undocumented behavior