Service endpoints.
WHAT TO DEFINE
Resources, and the operations on them Consistent response shapes, including errors Appropriate status codes
WHAT TO RETURN FOR ERRORS
A consistent structure, with a code the client can act on.
WHAT NOT TO RETURN
Internal exception detail.
WHAT TO VALIDATE
Every input, on the server, without exception.
WHAT TO USE
Model validation, plus explicit checks for business rules.
WHAT TO IMPLEMENT
Authentication Authorisation, on the specific record not only the endpoint Rate limiting Pagination on collections
WHY AUTHORISATION ON THE RECORD
Checking only that someone is signed in allows them to alter an identifier and reach another user's data.
WHAT TO DOCUMENT
The API, generated from the code where possible.
WHAT TO VERSION
The API, before others depend on it.
WHAT TO CONFIGURE
Cross-origin rules, restrictively.
WHAT TO LOG
Requests, failures and timings, with correlation identifiers.
WHAT TO NEVER LOG
Credentials, tokens or personal data beyond what is necessary.
WHAT TO TEST
Every endpoint, including unauthorised access attempts.
