API Response Shaping, Done Properly
Deciding what data an API returns, how it is structured and how clients request more or less of it.
Marcus Adeyemi
Where most projects go wrong
The usual mistakes:
- Returning database models directly
- Internal fields exposed by accident
- Different shapes for the same resource
- Breaking changes without versioning
What good looks like instead
- Transform models rather than returning them directly
- Whitelist fields explicitly
- Support including related data on request
- Keep response shapes stable
- Document every field
Why it matters
Over-fetching wastes bandwidth and leaks data, while under-fetching forces clients into many round trips.
The specs that matter
| Measure | Figure |
|---|---|
| Resources | transform internal models into stable public shapes |
| Field selection | lets clients request only what they need |
| Versioning | response shape changes can break clients |
| Sensitive fields | internal attributes must not leak |
Knowing when to hand it over
Tip: Bring in help when APIs serve external developers.
Where this comes from
- Laravel Documentation — Eloquent: API resources
- Microsoft Learn — Web API design best practices
The figures and practices above come from the sources listed.
Working on something like this?
We take on Web Design & Development work for teams who want it done once, properly. Tell us what you are building and we will tell you honestly whether we are the right studio for it. Start a project.
Where to go next
Spotted something wrong? Report an error on this page. We correct on the page and say what changed.
