Designing Real-World REST APIs for Products, Not Tutorials

Tutorials vs Real Products

Tutorial APIs are cute: `/users`, `/posts`, `/comments`. Real products have:

• Permissions
• Audit logs
• Weird edge cases from business rules

In Sehatdastak (100+ APIs) and an Amazon Seller Central clone, I had to keep the API layer predictable for years, not just for the first release.

My API Design Checklist

1. Stable Resource Names

• Use nouns, not verbs: `/patients`, `/appointments`, `/orders`
• Use plural for collections, keep it consistent

2. Clear Filtering & Pagination

• Always support `limit`, `offset` or `page`, `pageSize`
• Explicit filter params: `status`, `fromDate`, `toDate`, `role`
• Never hide pagination behind “load more” without docs

3. Consistent Error Shape

Every error returns:

• `code` (machine-readable)
• `message` (human-readable)
• Optional `fields` for validation errors

4. Versioning Strategy

I prefer:

• Semantic changes behind feature flags or query params first
• True breaking changes in `/v2` only when absolutely necessary

Takeaway

The best compliment for an API is not “clever” — it’s boring and predictable.