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 CarelineOS (100+ APIs) and StoreParity, 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.