Stop Building APIs Without These 5 Rules

Bad APIs don't just slow down development. They break products, frustrate teams, and create technical debt that takes months to clean up.
After 6 years of building and consuming APIs across dozens of products, here are the 5 rules I never skip.

1. Version From Day One
   /api/v1/users — not /api/users.
   You will change your API. Guaranteed. Without versioning from day one, every breaking change breaks every client consuming it. With versioning, you deprecate cleanly and move fast without fear.

2. Return Consistent Error Responses
   Every error should return the same shape:
   json{
   "status": 400,
   "error": "INVALID_INPUT",
   "message": "Email field is required"
   }
   Inconsistent error responses make frontend integration a nightmare. Standardize it once, document it, never deviate.

3. Never Expose Raw Database Errors
   A raw PostgreSQL error leaking into an API response is both a security risk and a terrible user experience.
   Always catch, log internally, and return a clean, human-readable error to the client. What happens inside your database stays inside your database.

4. Paginate Everything That Returns a List
   That endpoint returning 10 records today will return 100,000 in two years.
   Build pagination in from the start, cursor-based for performance at scale, offset-based if simplicity matters more. No list endpoint should ever return unbounded results.

5. Rate Limit Before You Need To
   Rate limiting feels unnecessary until your API gets hammered and your database goes down.
   Tools like express-rate-limit (Node.js) or django-ratelimit (Python) take 20 minutes to implement. Add them before launch, not after the incident.

These aren't advanced concepts. They're fundamentals, and the APIs that skip them always pay for it later.
If you want to see how I apply these principles in real production systems, check out my work at Backend Engineering Portfolio.