The Complete Guide to API Design in 2026: REST, GraphQL, and tRPC in Production
The API design landscape in 2026 settled into three clear patterns. REST for public APIs and microservices. GraphQL for complex data requirements. tRPC for TypeScript-to-TypeScript full-stack applications.
Each has a legitimate use case. The mistakes happen when teams choose based on hype rather than fit.
REST in 2026: Still the Default for a Reason
REST APIs remain the dominant pattern for:
- Public and partner APIs (ease of documentation and tooling)
- Microservices that need simple, well-defined contracts
- Teams without TypeScript full-stack expertise
The key REST improvements in 2026:
Better Error Responses
{
"error": {
"code": "VALIDATION_ERROR",
"message": "Request validation failed",
"details": [
{
"field": "email",
"code": "INVALID_FORMAT",
"message": "Must be a valid email address"
}
],
"requestId": "req_a1b2c3d4e5"
}
}
The requestId addition transformed our debugging. Every error now links to structured logs.
API Versioning
Still the most contentious topic. Our 2026 recommendation: URL versioning for major breaking changes only.
GET /v1/users ← Major version, breaking changes
GET /users?since= ← Minor additions, no versioning
Rate Limiting Headers
Standardized rate limit headers finally emerged as a convention:
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1716560400
Retry-After: 3600
GraphQL: When It's Actually the Right Choice
GraphQL shines when:
Complex, nested data requirements: A dashboard that pulls users, their orders, the products in those orders, and supplier data for those products. With REST, this requires 4+ requests or a massively overfetching endpoint.
Multiple client types: Mobile (needs different data than desktop) and web clients with different requirements. GraphQL's flexible queries handle this cleanly.
Rapid client evolution: When your mobile and web teams work independently, GraphQL's schema contract reduces coordination overhead.
When GraphQL Is Wrong
- Simple CRUD: If you're mostly doing Create, Read, Update, Delete on single resources, REST is simpler and has better tooling for this pattern.
- File uploads: Still awkward in GraphQL. Use REST for this.
- Caching: REST with HTTP caching is simpler and more efficient for publicly cacheable data.
The Schema Design Discipline
GraphQL's superpower is the type system. But it requires discipline:
type User {
id: ID!
email: String!
createdAt: DateTime!
# Explicitly define what's included, avoid N+1
orders(first: Int, after: String): OrderConnection!
totalOrderCount: Int! # Pre-computed, not derived
}
type OrderConnection {
edges: [OrderEdge!]!
pageInfo: PageInfo!
totalCount: Int!
}
The totalCount as a separate field (pre-computed) prevents COUNT(*) queries on every request.
tRPC: The TypeScript Revolution
tRPC became the default for TypeScript monorepos in 2025-2026. The appeal is real: end-to-end type safety without code generation.
// Server: define the procedure
const userRouter = router({
getById: publicProcedure
.input(z.object({ id: z.string() }))
.query(async ({ input }) => {
return db.user.findUnique({ where: { id: input.id } });
}),
});
// Client: fully typed, no code generation
const user = await trpc.user.getById.query({ id: userId });
// user is typed based on the server definition
The productivity gains are real for teams already in TypeScript. The tradeoff: you need a TypeScript monorepo, and the learning curve for Zod schemas is real.
When to Choose tRPC
✅ Perfect for: Full-stack TypeScript teams, rapid development, internal tools, startups moving fast
❌ Not for: Multi-language environments, public APIs, teams without TypeScript expertise
The Decision Framework
Is your team TypeScript-first with a monorepo?
→ YES → tRPC for internal services, REST for public APIs
→ NO → Continue below
Do clients need different data shapes for the same endpoint?
→ YES → GraphQL
→ NO → Continue below
Is this a public/partner API?
→ YES → REST (better tooling, easier to document, broader client support)
→ NO → REST is probably fine, GraphQL if the data model is complex
The Tooling That Matters in 2026
For REST:
- Zod for input validation (replaced Joi and class-validator)
- Hono or Fastify for the framework (Express is showing its age)
- scalar or redocly for API documentation
For GraphQL:
- GraphQL Yoga 5 (replaced Apollo Server as the default)
- pothos or nexus for schema-first development
- Studio for Explorer and monitoring
For tRPC:
- tanstack-query as the client (works with tRPC natively)
- Zod for input validation
- Kysely for type-safe database queries
This article contains affiliate links. If you sign up through the links above, I may earn a commission at no additional cost to you.
Ready to Build Your Online Business?
Get started with Systeme.io for free — All-in-one platform for building your online business with AI tools.