API Design That Doesn't Embarrass You
A bad API is forever. Here are the principles I follow to design APIs that developers actually enjoy using — and that age well.
Naming Is Everything
Consistent, predictable naming is the single highest-leverage thing you can do for API DX. Resources are nouns, plural. Actions are verbs only when there's no clean noun (/auth/logout, not /logoutUser).
Modeling Resources, Not Operations
REST is about resources, not procedures. If you find yourself naming endpoints after verbs, you're probably designing RPC over HTTP. That's fine — just be intentional about it and use tRPC.
Error Responses People Can Actually Use
An HTTP status code is not enough. Return a machine-readable error code, a human-readable message, and enough context to debug the problem. I follow RFC 7807 (Problem Details) for all error responses.
Versioning Strategy
URL versioning (/v1/) for breaking changes. Header versioning for minor variations. Never version by date — that's just confusion wearing a calendar. Maintain N-1 versions minimum, communicate deprecation 6 months in advance.
Pagination That Scales
Offset pagination breaks at scale. A query with OFFSET 50000 scans 50,000 rows to throw them away. Use cursor-based pagination for anything that might grow beyond a few thousand records.
Documentation as a Product
I treat API docs as a product, not an afterthought. OpenAPI spec checked into version control, generated from code annotations, published automatically on deploy. Developers read docs before they read code — make them good.
