API Design Best Practices in 2026: REST, GraphQL, and tRPC

"Should we use REST or GraphQL?" is the wrong question. The right question is: "What is the relationship between our API consumer and producer?" Here is how I decide on every project.

REST: still the default

For public APIs, third-party integrations, and any API consumed by parties you do not control — REST is still the right answer. Cacheable, simple, universally understood. Use proper HTTP verbs, status codes, and HATEOAS where it makes sense.

REST done right

• Resource-based URLs (/api/v1/users/123/orders, not /api/getUserOrders?id=123).
• Use HTTP verbs (GET, POST, PUT, PATCH, DELETE).
• Return appropriate status codes (200, 201, 400, 401, 403, 404, 422, 500).
• Version in URL (/api/v1/) or header.
• Pagination, filtering, sorting via query params.
• Rate limiting headers (X-RateLimit-Remaining).

GraphQL: when the client is your team

GraphQL shines when frontend and backend are owned by the same org and the frontend has diverse data needs (mobile app, web app, admin panel all hitting the same API). Avoids over-fetching and under-fetching.

Do not use GraphQL when: the API is consumed by third parties, caching is critical, your team has not used it before. Operational complexity is real.

tRPC: when frontend and backend are TypeScript

If both ends are TypeScript (Next.js + Node backend), tRPC gives you end-to-end type safety with zero schema duplication. Faster to build than REST, type-safe like GraphQL, less ceremony than either.

The decision tree

1. Public API or third-party? → REST.
2. Internal, complex data graph, multiple clients? → GraphQL.
3. Internal, TypeScript end-to-end, monorepo? → tRPC.
4. Real-time? → WebSockets or Server-Sent Events on top of any of the above.

The non-negotiables

• Authentication via JWT or session cookies.
• Rate limiting on every endpoint.
• OpenAPI/Swagger documentation that is generated from code, not handwritten.
• Versioning strategy from day 1.
• Structured error responses (RFC 7807 problem details).

Designing an API? I can review your design before you ship and prevent the mistakes that take months to fix.