jbvc/api-patterns
API design principles and decision-making. REST vs GraphQL vs tRPC selection, response formats, versioning, pagination.
67
Quality
67%
Does it follow best practices?
Impact
Pending
No eval scenarios have been run
Securityby
Passed
No known issues
response.md
Response Format Principles
Consistency is key - choose a format and stick to it.
Common Patterns
Choose one:
├── Envelope pattern ({ success, data, error })
├── Direct data (just return the resource)
└── HAL/JSON:API (hypermedia)Error Response
Include:
├── Error code (for programmatic handling)
├── User message (for display)
├── Details (for debugging, field-level errors)
├── Request ID (for support)
└── NOT internal details (security!)Pagination Types
| Type | Best For | Trade-offs |
|---|---|---|
| Offset | Simple, jumpable | Performance on large datasets |
| Cursor | Large datasets | Can't jump to page |
| Keyset | Performance critical | Requires sortable key |
Selection Questions
- How large is the dataset?
- Do users need to jump to specific pages?
- Is data frequently changing?