REST API Best Practices and Anti-Patterns

List endpoints should return a predictable structure for data, pagination, and errors.

# Use the same top-level response structure across endpoints.

X-Request-Id: req_01HXYZ123

# Make support and debugging easier.

2026-03-27T22:15:00Z

# Prefer explicit timezone-aware datetime strings.

RateLimit-Limit: 100
RateLimit-Remaining: 24
RateLimit-Reset: 60

# Help clients back off safely.

curl -X GET https://api.example.com/v1/users/usr_123 \
  -H "Authorization: Bearer $TOKEN"

# Show real requests and responses in docs.

Avoid: POST /createUser
Prefer: POST /users

# Avoid route names that duplicate the HTTP method.

Avoid: HTTP 200 with { "success": false } for validation failures

# Use HTTP status codes meaningfully.

Avoid exposing internal table names, join tables, and migration-driven field names directly.

# Keep API models stable and intentional.

Avoid removing fields or changing meanings without deprecation and migration guidance.

# Version or phase in incompatible changes.

Avoid: /orgs/{orgId}/teams/{teamId}/projects/{projectId}/tickets/{ticketId}/comments

# Keep URLs maintainable.