What goes in the body.
WHAT FORMAT TO USE
Structured text, almost always.
WHAT TO DECIDE
Field naming convention, applied everywhere.
WHAT TO RETURN FOR A SINGLE ITEM
The item, or the item wrapped in an envelope.
WHAT AN ENVELOPE PROVIDES
Room for metadata alongside the data.
WHAT IT COSTS
An extra level for every caller to unwrap.
WHAT TO DECIDE ONCE
Whether you use one, and never mix.
WHAT COLLECTIONS SHOULD RETURN
The items, plus pagination information.
WHAT TO INCLUDE FOR EVERY ITEM
Its identifier Timestamps for creation and last change
WHY TIMESTAMPS ALWAYS
Callers need them for synchronisation, and adding them later is disruptive.
WHAT TO BE CAREFUL WITH
Numbers that should be strings Dates in ambiguous formats Money as floating point Empty values meaning several different things
WHAT TO USE FOR DATES
A single unambiguous standard, with the offset included.
WHY THAT MATTERS ENORMOUSLY
A date without a zone is interpreted differently by every caller.
WHAT TO USE FOR MONEY
An integer of the smallest unit, plus a currency code.
WHY
It removes rounding entirely.
WHAT TO DISTINGUISH
A field absent, a field present and empty, and a field explicitly null.
WHY
They mean different things during updates.
