Resource-oriented interfaces.
WHAT THE APPROACH IS
Resources identified by addresses, acted on with standard methods.
WHAT THE METHODS MEAN
Retrieve, without changing anything Create Replace Update partially Remove
WHAT TO NEVER DO
Change state with a retrieval.
WHY
It can be triggered by a link, an image or a crawler.
WHAT TO NAME RESOURCES
Nouns, in the plural, describing collections and items.
WHAT NOT TO PUT IN ADDRESSES
Verbs describing actions.
WHAT TO RETURN
Appropriate status codes matching what actually happened.
WHY THAT MATTERS
Returning success for a failure breaks every client.
WHAT TO MAKE CONSISTENT
The shape of every response, including errors.
WHY
Inconsistency produces defensive code in every client.
WHAT TO IMPLEMENT ON COLLECTIONS
Pagination, always.
WHY
An unpaginated collection endpoint eventually returns everything, and eventually fails.
WHAT ELSE TO SUPPORT
Filtering and sorting, where useful.
WHAT TO DOCUMENT
Every endpoint: purpose, inputs, outputs, and failure modes.
