API Design Best Practices: Pagination, Errors, Versioning & Type Safety
Great API design focuses on consumer experience, long-term maintainability, and safe evolution. Key areas include pagination strategy, meaningful error responses, versioning approach, and type safety between frontend and backend.
Pagination = how you serve large orders efficiently. Error handling = clear communication when something goes wrong. Versioning = updating the menu without confusing regular customers. Type safety = ensuring the kitchen and waiter always speak the same language.
1Pagination Strategies
Offset-based for page navigation (admin tools). Cursor-based for infinite scroll and timelines (more stable under inserts/deletes).
2Error Response Design
Always return structured errors with machine-readable codes, human messages, and field-level details. Use standard HTTP status codes appropriately.
3API Versioning
URL path versioning is most explicit. Header versioning keeps URLs clean. Plan deprecation paths from day one.
4Type Safety Approaches
OpenAPI/Swagger for broad compatibility. tRPC for full-stack TypeScript. GraphQL for flexible, self-documenting contracts.
| Property | Offset Pagination | Cursor Pagination |
|---|---|---|
| Use Case | Admin panels, page numbers | Infinite scroll, timelines |
| Stability | Low (shifts on inserts) | High |
| Complexity | Low | Medium |
Offset Pagination
Use Case
Admin panels, page numbers
Stability
Low (shifts on inserts)
Complexity
Low
Cursor Pagination
Use Case
Infinite scroll, timelines
Stability
High
Complexity
Medium
Common questions
- ›“How do you design pagination for a large list?”
- ›“What makes a good error response?”
- ›“How should you version APIs?”
- ›“How do you ensure type safety between frontend and backend?”
What interviewers look for
- Understanding of cursor vs offset trade-offs
- Focus on actionable, consistent errors
- Awareness of versioning strategies and deprecation
- Practical type safety solutions (OpenAPI, tRPC, etc.)
Short answer (60 sec)
Use cursor-based pagination for infinite scroll and offset for page navigation. Return structured errors with codes and details. Version explicitly (URL path is clearest). Use OpenAPI or tRPC for type safety.
Detailed answer (senior level)
Well-designed APIs prioritize consumer ergonomics and safe evolution. Cursor pagination avoids instability in dynamic lists. Errors should be machine-readable and actionable. Versioning should be planned early with clear deprecation. Strong type safety (via OpenAPI or tRPC) reduces integration bugs and improves developer experience.
- Using offset pagination for infinite scroll
- Returning vague or inconsistent error messages
- No versioning strategy until breaking changes occur
- Manually syncing types between frontend and backend
- Over-fetching or chatty endpoints
- ✓Choose pagination strategy based on UX (cursor for infinite scroll)
- ✓Design clear, actionable error responses with codes
- ✓Plan API versioning and deprecation from the start
- ✓Invest in type safety (OpenAPI, tRPC, or GraphQL)
- ✓Keep APIs predictable and easy to evolve
- ✓Balance flexibility with operational simplicity
- ✓Good APIs make frontend development faster and safer
Related web fundamentals topics
Continue with closely related browser and frontend engineering concepts.