REST API Best Practices: Designing Better JSON APIs (2026)

What Makes a Great REST API?

A well-designed REST API is intuitive, consistent, and developer-friendly. Whether you are building internal microservices or public APIs, following established patterns ensures your API scales with your business needs.

1. Use Proper HTTP Status Codes

Status codes communicate result without parsing the body:

• 200 OK - Successful GET, PUT, PATCH
• 201 Created - Successful POST with new resource
• 204 No Content - Successful DELETE
• 400 Bad Request - Client error (validation failed)
• 401 Unauthorized - Authentication required
• 403 Forbidden - Insufficient permissions
• 404 Not Found - Resource does not exist
• 422 Unprocessable Entity - Semantic errors
• 500 Internal Server Error - Server error

2. Consistent URL Structure

Follow resource-oriented naming:

Good:

• GET /users - List users
• GET /users/123 - Get specific user
• POST /users - Create user
• PUT /users/123 - Update user
• DELETE /users/123 - Delete user

Bad:

• GET /getUsers
• POST /createUser
• GET /user/123/delete

3. Version Your API

Always version from day one:

URL Path (Recommended):

• /v1/users
• /v2/users

Header (Alternative):

• Accept: application/vnd.api+json;version=2

4. Standardize Response Format

Use a consistent envelope structure:

Success Response: { "data": { ... }, "meta": { "timestamp": "2026-05-01T12:00:00Z", "requestId": "uuid" } }

Error Response: { "error": { "code": "VALIDATION_ERROR", "message": "Email is required", "details": [{ "field": "email", "issue": "missing" }] } }

5. Implement Proper Pagination

Never return unbounded lists:

Offset Pagination: GET /users?limit=20&offset=40 { "data": [...], "pagination": { "total": 1000, "limit": 20, "offset": 40, "hasMore": true } }

Cursor Pagination (Better for large datasets): GET /users?limit=20&cursor=eyJpZCI6MTIzfQ

6. Handle Errors Gracefully

Provide actionable error messages:

Bad: { "error": "Something went wrong" }

Good: { "error": { "type": "ValidationError", "code": "INVALID_EMAIL", "message": "The email address 'invalid' is not valid.", "field": "email", "suggestion": "Please provide a valid email like [email protected]" } }

7. Use Filtering and Sorting

Allow flexible data retrieval:

GET /users?status=active&sort=-createdAt&fields=id,name,email

• Filtering: ?status=active
• Sorting: ?sort=-createdAt (minus = descending)
• Field selection: ?fields=id,name

8. Implement Rate Limiting

Protect your API from abuse:

Headers: X-RateLimit-Limit: 1000 X-RateLimit-Remaining: 999 X-RateLimit-Reset: 1640995200

Response when limited (429): { "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Too many requests. Please try again in 60 seconds." } }

9. Support CORS Properly

Enable cross-origin requests securely:

Headers: Access-Control-Allow-Origin: https://yourdomain.com Access-Control-Allow-Methods: GET, POST, PUT, DELETE Access-Control-Allow-Headers: Content-Type, Authorization Access-Control-Max-Age: 86400

10. Document Your API

Use OpenAPI (Swagger) for interactive documentation:

• Document all endpoints
• Include request/response examples
• Specify authentication requirements
• Provide error scenarios
• Keep docs synchronized with code

Anti-Patterns to Avoid

• Chattiness: Requiring multiple calls for basic operations
• Inconsistency: Different naming conventions across endpoints
• Over-fetching: Returning unnecessary data
• Under-fetching: Requiring multiple requests for related data (consider GraphQL)
• No caching: Missing Cache-Control headers

Conclusion

Great APIs are designed with the developer experience in mind. Follow these REST API best practices to build APIs that are intuitive, scalable, and maintainable. Test your API responses with our JSON formatter to ensure consistent, valid JSON output.