The response your API sends back is the only thing most developers will ever see. You can have the cleanest internal architecture in the world, but if your responses are inconsistent, hard to parse, or missing critical metadata, developers will struggle.
This guide covers how to design API responses that are predictable, efficient, and easy to work with — using the PetStore API as a reference throughout.
A well-designed response answers three questions immediately:
Let's break down each piece.
A response envelope is a consistent wrapper around your actual data. There are two schools of thought here.
No envelope (direct response):
{
"id": 10,
"name": "Max",
"status": "available",
"photoUrls": ["https://example.com/max.jpg"]
}
This is what the PetStore API does for single-resource responses. The HTTP status code tells you if it succeeded, and the body is the resource itself. Clean and simple.
With envelope:
{
"success": true,
"data": {
"id": 10,
"name": "Max",
"status": "available",
"photoUrls": ["https://example.com/max.jpg"]
},
"meta": {
"timestamp": "2024-03-13T10:30:00Z",
"version": "3.0"
}
}
The envelope approach gives you a consistent structure across all responses, including errors. It also provides a place for metadata that doesn't belong in the resource itself.
Which should you use?
For simple APIs, no envelope is cleaner. For complex APIs with lots of metadata, pagination, or mixed response types, an envelope makes life easier. Pick one approach and stick to it across your entire API.
Error responses need to be as well-designed as success responses. Developers will spend more time debugging errors than celebrating successes.
PetStore-style error response:
{
"code": 404,
"type": "error",
"message": "Pet not found"
}
Simple, but missing some useful information. A more complete error response might look like:
{
"error": {
"code": "PET_NOT_FOUND",
"message": "No pet exists with ID 10",
"details": "The pet may have been deleted or the ID may be incorrect",
"timestamp": "2024-03-13T10:30:00Z",
"path": "/pet/10",
"requestId": "req_abc123"
}
}
Key elements of a good error response:
PET_NOT_FOUNDValidation errors need field-level detail:
{
"error": {
"code": "VALIDATION_ERROR",
"message": "Request validation failed",
"fields": [
{
"field": "name",
"message": "Name is required",
"code": "REQUIRED_FIELD"
},
{
"field": "photoUrls",
"message": "At least one photo URL is required",
"code": "REQUIRED_FIELD"
}
]
}
}
This lets clients highlight specific form fields that need correction.
Python example handling errors:
import requests
def get_pet(pet_id):
response = requests.get(
f"https://petstore3.swagger.io/api/v3/pet/{pet_id}",
headers={"api_key": "your-api-key"}
)
if response.status_code == 200:
return response.json()
# Handle errors
error = response.json()
error_code = error.get("code") or error.get("error", {}).get("code")
if error_code == "PET_NOT_FOUND":
print(f"Pet {pet_id} doesn't exist")
return None
elif response.status_code == 401:
print("Authentication failed - check your API key")
return None
else:
print(f"Unexpected error: {error.get('message')}")
return None
When you're returning a list of resources, you need pagination. Returning 10,000 pets in one response is neither practical nor performant.
Offset-based pagination (simple but limited):
GET /pets?limit=20&offset=40
Response:
{
"data": [
{ "id": 41, "name": "Buddy", "status": "available" },
{ "id": 42, "name": "Luna", "status": "pending" }
// ... 18 more pets
],
"pagination": {
"limit": 20,
"offset": 40,
"total": 500,
"hasMore": true
}
}
Offset pagination is easy to understand but has problems at scale — if items are added or removed between requests, you can miss items or see duplicates.
Cursor-based pagination (better for large datasets):
GET /pets?limit=20&cursor=eyJpZCI6NDAsInRpbWVzdGFtcCI6MTY0...
Response:
{
"data": [
{ "id": 41, "name": "Buddy", "status": "available" },
{ "id": 42, "name": "Luna", "status": "pending" }
],
"pagination": {
"limit": 20,
"nextCursor": "eyJpZCI6NjAsInRpbWVzdGFtcCI6MTY0...",
"hasMore": true
}
}
The cursor is an opaque token that encodes the position in the result set. Clients don't need to understand it — they just pass it back for the next page.
Page-based pagination (most intuitive for users):
GET /pets?page=3&perPage=20
Response:
{
"data": [ /* ... */ ],
"pagination": {
"page": 3,
"perPage": 20,
"totalPages": 25,
"totalItems": 500
}
}
Page-based pagination is the most user-friendly for UIs with page numbers, but has the same consistency issues as offset pagination.
Include pagination links (HATEOAS-style):
{
"data": [ /* ... */ ],
"pagination": {
"page": 3,
"perPage": 20,
"totalPages": 25
},
"links": {
"first": "/pets?page=1&perPage=20",
"prev": "/pets?page=2&perPage=20",
"self": "/pets?page=3&perPage=20",
"next": "/pets?page=4&perPage=20",
"last": "/pets?page=25&perPage=20"
}
}
This makes it trivial for clients to navigate without constructing URLs themselves.
Sometimes clients only need a few fields from a resource. Sending the entire object wastes bandwidth and processing time.
Field selection with query parameters:
GET /pets/10?fields=id,name,status
Response:
{
"id": 10,
"name": "Max",
"status": "available"
}
The photoUrls, tags, and other fields are omitted because they weren't requested.
Nested field selection:
GET /pets/10?fields=id,name,category(id,name)
Response:
{
"id": 10,
"name": "Max",
"category": {
"id": 1,
"name": "Dogs"
}
}
This is particularly useful for mobile clients on slow connections or when you're fetching many resources at once.
JavaScript example using field selection:
async function getPetSummary(petId) {
const fields = 'id,name,status';
const response = await fetch(
`https://petstore3.swagger.io/api/v3/pet/${petId}?fields=${fields}`,
{
headers: { 'api_key': 'your-api-key' }
}
);
return response.json();
}
// Returns only the fields we need, reducing payload size
const summary = await getPetSummary(10);
console.log(summary); // { id: 10, name: "Max", status: "available" }
Metadata provides context about the response that isn't part of the resource itself.
Common metadata fields:
{
"data": { /* ... */ },
"meta": {
"timestamp": "2024-03-13T10:30:00Z",
"version": "3.0",
"requestId": "req_abc123",
"processingTime": 45,
"cached": false,
"cacheExpiry": "2024-03-13T10:35:00Z"
}
}
This metadata is invaluable for debugging performance issues and understanding cache behavior.
Large responses should be compressed. Most HTTP clients handle this automatically, but your server needs to support it.
Enable gzip compression:
Request:
GET /pets
Accept-Encoding: gzip, deflate
Response headers:
Content-Encoding: gzip
Content-Length: 1234
The response body is compressed, reducing bandwidth by 70-90% for JSON responses.
When to compress:
Most web frameworks (Express, Flask, Django, etc.) have middleware that handles this automatically.
Different clients want different formats. Content negotiation lets them specify what they prefer.
JSON (default):
GET /pets/10
Accept: application/json
Response:
{
"id": 10,
"name": "Max",
"status": "available"
}
XML:
GET /pets/10
Accept: application/xml
Response:
<?xml version="1.0" encoding="UTF-8"?>
<Pet>
<id>10</id>
<name>Max</name>
<status>available</status>
</Pet>
The PetStore API supports both JSON and XML via the Accept header.
Custom media types:
Accept: application/vnd.petstore.v3+json
This lets you version your response format independently of your API version.
Language negotiation:
Accept-Language: es-ES, es;q=0.9, en;q=0.8
If your API returns user-facing messages, respect the Accept-Language header to return localized content.
Always use ISO 8601 format for dates and times:
{
"createdAt": "2024-03-13T10:30:00Z",
"updatedAt": "2024-03-13T14:45:30Z",
"shipDate": "2024-03-15T00:00:00Z"
}
The Z suffix means UTC. If you need to include timezone information:
{
"scheduledAt": "2024-03-15T09:00:00-05:00"
}
Never use ambiguous formats like 03/13/2024 (is that March 13 or December 3?) or Unix timestamps (hard for humans to read).
There's a semantic difference between a field being null and a field being absent.
Field is null:
{
"id": 10,
"name": "Max",
"description": null
}
This means the description field exists but has no value.
Field is missing:
{
"id": 10,
"name": "Max"
}
This means the description field doesn't apply to this resource or wasn't requested.
Be consistent about which approach you use. For sparse fieldsets, omitting fields makes sense. For full representations, including null fields makes the schema more explicit.
Sometimes clients need related resources in the same request. Embedding them reduces round trips.
Without embedding:
GET /pets/10
Response:
{
"id": 10,
"name": "Max",
"categoryId": 1
}
The client needs a second request to get the category details.
With embedding:
GET /pets/10?embed=category
Response:
{
"id": 10,
"name": "Max",
"category": {
"id": 1,
"name": "Dogs"
}
}
Now the category is included directly. This is especially useful for mobile clients trying to minimize requests.
Go example with embedded resources:
type Pet struct {
ID int64 `json:"id"`
Name string `json:"name"`
Category *Category `json:"category,omitempty"`
}
type Category struct {
ID int64 `json:"id"`
Name string `json:"name"`
}
func getPet(petID int64, embed bool) (*Pet, error) {
url := fmt.Sprintf("https://petstore3.swagger.io/api/v3/pet/%d", petID)
if embed {
url += "?embed=category"
}
resp, err := http.Get(url)
if err != nil {
return nil, err
}
defer resp.Body.Close()
var pet Pet
if err := json.NewDecoder(resp.Body).Decode(&pet); err != nil {
return nil, err
}
return &pet, nil
}
Beyond the body, response headers provide important context.
Cache control:
Cache-Control: public, max-age=3600
ETag: "33a64df551425fcc55e4d42a148795d9f25f89d4"
Tells clients they can cache this response for an hour and provides an ETag for conditional requests.
Rate limiting:
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 987
X-RateLimit-Reset: 1710331800
Lets clients know how many requests they have left and when the limit resets.
Pagination (Link header):
Link: </pets?page=2>; rel="next", </pets?page=10>; rel="last"
An alternative to including pagination links in the response body.
Response design is about empathy. Put yourself in the developer's shoes: what information do they need to handle this response correctly? What metadata would make debugging easier? How can you make the structure predictable across all endpoints?
The patterns here — consistent envelopes, detailed error responses, thoughtful pagination, field selection, proper metadata — are what separate APIs that are merely functional from APIs that are a joy to work with.
The PetStore API gets the basics right: clean JSON responses, consistent error format, and standard HTTP status codes. Use it as a baseline, then layer on the patterns that make sense for your specific use case.
