JSON Best Practices for API Development
Well-designed JSON APIs are easier to use, maintain, and scale. Follow these best practices for better API design.
Naming Conventions
Use Consistent Case
Pick one naming convention and stick with it:
Recommendation: Use camelCase for JSON APIs as it matches JavaScript conventions.
Be Descriptive
Wrong:
{"n": "John", "a": 30}
Right:
{"name": "John", "age": 30}
Clear names make APIs self-documenting.
Use Plural for Collections
{"users": [...]} not {"user": [...]}
{"items": [...]} not {"item": [...]}
Structure
Envelope Pattern
Wrap responses in a consistent envelope:
{
"data": {...},
"meta": {
"page": 1,
"total": 100
}
}
This allows adding metadata without breaking changes.
Error Responses
Provide structured error information:
{
"error": {
"code": "VALIDATION_ERROR",
"message": "Email is required",
"field": "email"
}
}
Pagination
Include pagination info for list endpoints:
{
"data": [...],
"pagination": {
"page": 1,
"perPage": 20,
"total": 100,
"totalPages": 5
}
}
Data Types
Use Appropriate Types
Wrong:
{"age": "30", "isActive": "true"}
Right:
{"age": 30, "isActive": true}
Use proper JSON types, not strings for everything.
Dates
Use ISO 8601 format for dates:
{"createdAt": "2025-01-15T10:30:00Z"}
This is unambiguous and sortable.
Money
Use integers for money (cents/smallest unit):
{"priceInCents": 1999}
Or use strings for precise decimals:
{"price": "19.99", "currency": "USD"}
IDs
Use strings for IDs even if they're numbers:
{"id": "12345"}
This prevents integer overflow issues.
Null Values
Be Consistent
Decide whether to include null values or omit them:
Include: {"middleName": null}
Omit: {}
Both are valid, but be consistent.
Don't Use Empty Strings for Missing Data
Wrong:
{"phone": ""}
Right:
{"phone": null}
Or omit the field entirely.
Versioning
Version Your API
Include version in the URL or header:
URL: /api/v1/users
Header: Accept: application/vnd.api+json; version=1
Avoid Breaking Changes
When evolving your API:
Performance
Minimize Response Size
Only include necessary fields. Consider supporting field selection:
GET /users?fields=id,name,email
Use Compression
Enable gzip/brotli compression for JSON responses.
Consider Pagination
Never return unbounded lists:
Wrong: GET /users (returns 10,000 users)
Right: GET /users?page=1&limit=20
Security
Validate Input
Always validate JSON input:
Don't Expose Internal Details
Wrong:
{"error": "SQLException: table users..."}
Right:
{"error": "An error occurred"}
Log details server-side, don't expose them.
Conclusion
Following these best practices leads to APIs that are easier to use, maintain, and scale. Use JSONSpark to format and validate your JSON during development.