Request and Response Body Design
What you'll learn: How to structure JSON payloads with clear naming conventions while preventing clients from fetching unnecessary data.
Core Concept
When designing API request and response bodies, you're creating the data contract between client and server. Poor design leads to confusion, bloated responses, and wasted bandwidth. Great design makes your API intuitive, efficient, and maintainable.
Structuring JSON Payloads
Keep your JSON structure flat when possible, but nest logically related data:
// Good: Clear hierarchy
{
"user": {
"id": "u123",
"email": "alice@example.com",
"profile": {
"firstName": "Alice",
"lastName": "Smith"
}
}
}
Group related fields together, but avoid excessive nesting (3+ levels gets hard to navigate).
Field Naming Conventions
Pick one style and stick to it:
camelCase(JavaScript-friendly):firstName,userIdsnake_case(Python/Ruby-friendly):first_name,user_id
Use descriptive names: createdAt beats ct, isActive beats act. Boolean fields should sound like yes/no questions (isVerified, hasAccess).
Avoiding Over-Fetching
Think of over-fetching like ordering a pizza when you only wanted one slice—wasteful and slow. Return only what the client needs for that specific use case:
// Bad: Kitchen sink approach
GET /users/123 → returns 50 fields including full order history
// Good: Targeted response
GET /users/123 → returns core user data only
GET /users/123/orders → separate endpoint for orders
Consider field filtering via query parameters: GET /users/123?fields=id,email,firstName for power users who want control.
Key Takeaway: Design clean, consistent JSON structures with intuitive naming, appropriate nesting, and only the data each endpoint truly needs—treating bandwidth and parsing time as precious resources.