Practical construction.
WHAT TO DECIDE FIRST
What it is for, and who calls it.
WHAT TO DESIGN BEFORE CODING
The resources The paths The authentication The error format
WHY BEFORE
Changing these after callers exist is expensive.
WHAT FRAMEWORK TO USE
Whatever your team already knows.
WHY
Routing, validation and serialisation are solved everywhere.
WHAT TO IMPLEMENT IN ORDER
Authentication One resource, fully Errors and validation Pagination Documentation Everything else
WHY ONE RESOURCE FULLY
It establishes the patterns everything else follows.
WHAT TO VALIDATE
Every input, before it reaches business logic.
WHAT TO SEPARATE
Request handling from business logic.
WHY
It allows testing the logic without the interface, and reusing it elsewhere.
WHAT TO RETURN CONSISTENTLY
The same shapes, the same error format, the same conventions.
WHAT TO LOG
Every request, with a correlation identifier.
WHAT TO ADD EARLY
Rate limiting Request size limits Timeouts
WHAT TO TEST
Every endpoint, including failures and authorisation.
WHAT TO DO BEFORE PUBLISHING
Have someone else build against it, with only the documentation.
