The Other Side of the Request

Why build one after consuming several. Everything that annoyed you as a client is a decision someone made as a server. Inconsistent shapes, a count that lies, no way to page, errors that arrive as HTML. You now know what those cost, which is the right moment to design your own.

The decisions, in order.

Wrap your results in an object rather than returning a bare array, so there is room for a count and paging later. A bare array is a promise you cannot change.

Use status codes properly: 200 for success, 404 for absent, 400 for a bad request.

Return errors as JSON with the same shape every time.

Name your fields explicitly rather than serializing whole records, which is how private fields leak.

Document the five things you wished your sources had documented.