Designing Resource Representations
What you'll learn: How to structure the JSON body of your REST API responses so they're clear, complete, and easy to consume.
The Core Idea
A resource representation is the actual data format you send back when a client requests a resource. While the resource itself is the underlying concept (like "a user" or "an order"), the representation is how you package that data—typically as JSON.
Think of it like a business card: the person is the resource, but the card itself is the representation—it decides which fields to show (name, title, email) and how to organize them.
Structuring Your JSON
When designing representations, you must decide:
Which fields to include:
Only expose what clients need. A User resource might include id, username, email, and createdAt, but omit internal fields like passwordHash.
Appropriate data types:
Use numbers for IDs and counts, strings for text, booleans for flags, and ISO 8601 strings for dates ("2024-01-15T10:30:00Z").
Nesting related data:
If an Order belongs to a User, you might nest basic user info:
{
"id": 123,
"total": 49.99,
"user": {
"id": 456,
"username": "alice"
}
}
Avoid deep nesting—it makes responses hard to parse. For complex relationships, consider including just an ID or a link instead.
Consistency matters:
Use the same naming convention across all resources (snake_case or camelCase), and structure similar resources similarly. A collection should always return an array; single resources should return an object.
Practical Considerations
- Keep representations lean—don't send unnecessary data
- Match field names to your domain model where sensible
- Document your representation format clearly
Key Takeaway:
Design resource representations by choosing relevant fields, using correct data types, and nesting sparingly—prioritize clarity and consistency to make your API predictable and easy to use.