Designing Stable Response Envelopes
Standardize metadata, links, and error shapes so API consumers get predictable, backward-compatible payloads.
Why Response Envelopes Matter
A response envelope is a consistent outer shape that wraps every payload your API returns. Instead of returning bare data on one route and a different ad-hoc structure on another, you commit to ONE predictable skeleton.
Consumers benefit because they can:
- Write one parser that works across all endpoints
- Always know where to find
data,meta, anderrors - Rely on the shape staying backward-compatible as you add fields
In this lesson you will design stable envelopes for success, pagination, and errors in FastAPI.
The Bare-Data Anti-Pattern
The most common mistake is returning naked data and changing its shape per route. Here a list endpoint returns an array while a detail endpoint returns an object, and there is nowhere to attach pagination or warnings.
When you later need to add a total count, you must break the array contract or bolt on inconsistent fields. A pure dict has no room to grow safely.
# Anti-pattern: inconsistent, no room to grow
def list_users():
return [{"id": 1, "name": "Ada"}] # bare array
def get_user(user_id):
return {"id": user_id, "name": "Ada"} # bare object
# Later you need pagination... where does total go?
print(list_users())
print(get_user(1))All lessons in this course
- URL, Header and Media-Type Versioning
- Cursor vs Offset Pagination at Scale
- Dynamic Filtering and Sorting Parameters
- Designing Stable Response Envelopes