JSON API Best Practices for Developers

Published: May 26, 2025 · 7 min read

A well-designed JSON API is easy to use, consistent, and maintainable. Whether you're building a public API or an internal microservice, these best practices will help you create APIs that developers love working with.

1. Use Consistent Naming Conventions

Pick one naming style and stick to it across your entire API:

// ✅ camelCase (most common for JSON APIs) {"firstName": "Alice", "lastName": "Smith", "createdAt": "2025-01-15"} // ✅ snake_case (common in Python/Ruby ecosystems) {"first_name": "Alice", "last_name": "Smith", "created_at": "2025-01-15"} // ❌ Mixed (inconsistent — avoid this) {"firstName": "Alice", "last_name": "Smith", "Created_At": "2025-01-15"}

Rule: camelCase is the JavaScript/JSON convention. snake_case is common in Python APIs. Never mix both in the same API.

2. Structure Error Responses Consistently

Every error response should follow the same format:

{ "error": { "code": "VALIDATION_ERROR", "message": "Email address is invalid", "field": "email", "statusCode": 400 } }

Include: a machine-readable error code, a human-readable message, the field that caused the error (for validation), and the HTTP status code. This makes client-side error handling predictable and debuggable.

3. Implement Pagination for Lists

Never return unbounded lists. Always paginate:

{ "data": [...], "pagination": { "page": 1, "perPage": 20, "total": 156, "totalPages": 8 } }

Common approaches: offset-based (?page=2&per_page=20), cursor-based (?after=abc123), or keyset pagination. Cursor-based is best for large datasets as it doesn't slow down on later pages.

4. Use Proper HTTP Status Codes

Code	Meaning	When to Use
200	OK	Successful GET, PUT, PATCH
201	Created	Successful POST that creates a resource
204	No Content	Successful DELETE
400	Bad Request	Invalid input/validation error
401	Unauthorized	Missing or invalid auth token
403	Forbidden	Valid auth but insufficient permissions
404	Not Found	Resource doesn't exist
429	Too Many Requests	Rate limit exceeded
500	Server Error	Unexpected backend failure

5. Version Your API

Always version your API from day one. Breaking changes without versioning breaks every client:

// URL versioning (most common) GET /api/v1/users GET /api/v2/users // Header versioning Accept: application/vnd.myapi.v2+json

URL versioning is simpler and more visible. Keep old versions running for at least 6-12 months after deprecation.

6. Use ISO 8601 for Dates

Always return dates in ISO 8601 format with timezone:

// ✅ Good — unambiguous, timezone-aware {"createdAt": "2025-01-15T09:30:00Z"} // ❌ Bad — ambiguous format, no timezone {"createdAt": "01/15/2025 9:30 AM"}

7. Envelope Pattern vs Flat Responses

Wrap responses in a consistent envelope:

// Envelope pattern — recommended for public APIs { "success": true, "data": {"id": 1, "name": "Alice"}, "meta": {"requestId": "abc-123", "timestamp": "2025-01-15T09:30:00Z"} } // Flat pattern — simpler, common for internal APIs {"id": 1, "name": "Alice"}

The envelope pattern makes it easier to add metadata, handle errors consistently, and maintain backward compatibility.

8. Minimize Response Size

Only return fields the client needs (or support ?fields=name,email filtering)
Use gzip/brotli compression (saves 60-80% bandwidth)
Minify JSON in production (remove whitespace)
Avoid deeply nested structures — flatten when possible
Use pagination to limit response sizes

Tools for API Development

Use these tools to work with your API responses:

JSON Formatter — pretty-print API responses for debugging
JSON Compare — diff two API responses to spot changes
JSON Schema Generator — create schemas for API documentation
JSON to TypeScript — generate types from API responses
JSON Path Query — extract specific fields from complex responses