Designing Consistent Response Shapes
An API becomes easier to consume when similar endpoints use similar structures.
A collection might return an object containing data, pagination metadata, and links. A single resource can return the resource directly or consistently inside data, depending on the API convention.
Avoid unpredictable behavior such as returning an array from one collection endpoint and an object with items from another without a strong reason.
Consistency should also apply to dates, identifiers, naming conventions, errors, pagination, and null handling.
Representation Conventions
Dates:
ISO 8601 stringsUse an unambiguous format such as 2026-10-12T10:00:00Z.
IDs:
Stable identifiersDo not expose database-specific identifiers unless they are intentionally part of the public contract.
Null:
Document semanticsConsumers need to know whether null means unknown, absent, or intentionally empty.