RESTful API JSON Response Design: What Good Looks Like
2024-06-28
Every endpoint inventing its own shape forces client adapters. A small team envelope convention saves months of glue code.
Envelope
Optional { data, meta, errors }—consistency matters more than minimalism.
{ "data": { "id": 1 }, "meta": { "requestId": "abc" } }Errors
HTTP status + machine code + human message + field details array.
Pagination
Pick cursor or offset site-wide; name arrays consistently (data vs items).
Naming and time
camelCase or snake_case—not both; ISO 8601 date strings.
Evolution
Additive changes only in v1; breaking changes bump /v2/; update OpenAPI + fixtures.