API Development Guide: REST, GraphQL, tRPC in 2026
How to design and build modern APIs — REST, GraphQL, tRPC — with auth, versioning, docs, and rate limiting.
Choosing an API Style
REST: simple, cacheable, huge tooling. Best for public APIs and cross-team contracts.
GraphQL: flexible client-driven queries, single endpoint. Best for complex UIs and mobile apps.
tRPC: end-to-end typed RPC in TypeScript. Best when both ends are TypeScript.
REST Design
Nouns not verbs: /users/123/posts, not /getUserPosts.
HTTP methods: GET (read), POST (create), PUT/PATCH (update), DELETE.
Status codes correctly: 200, 201, 204, 400, 401, 403, 404, 409, 422, 429, 500, 503.
Pagination: cursor-based for large data; page-based OK for small.
Consistent error format (RFC 7807 problem details is a good choice).
GraphQL
Single POST endpoint, client selects fields.
N+1 queries are a real risk — use DataLoader.
Auth per-field via directives or resolvers.
Persisted queries + query complexity limits for prod.
tRPC
Procedures in TypeScript; client calls them with full type inference.
Zero schema drift between client and server.
Great with Next.js, TanStack Start, and other TS meta-frameworks.
REST vs GraphQL vs tRPC
| Dimension | REST | GraphQL | tRPC |
|---|---|---|---|
| Type safety | Manual (OpenAPI) | Schema-based | End-to-end (TS) |
| Public API friendly | Excellent | OK | No |
| Client flexibility | Low | High | N/A (RPC) |
| Caching | HTTP cache friendly | Custom | Custom |
| Ecosystem | Vast | Large | TS-only |
Auth
Browser: HttpOnly session cookies + CSRF protection.
Server-to-server: JWT or opaque tokens with short TTL.
Third-party: OAuth 2.0 + PKCE.
Never build your own OAuth server unless you have to.
Versioning
URL versioning: /v1/, /v2/. Simple, cache-friendly.
Header versioning: Accept: application/vnd.api.v2+json. Cleaner URLs.
Deprecation policy documented and communicated in advance.
Rate Limiting & Observability
Rate limit by API key + IP.
Return 429 with Retry-After header.
Structured logging (JSON) + tracing (OpenTelemetry).
Uptime monitoring + on-call rotation for production APIs.
Docs
OpenAPI (Swagger) for REST. Generates docs + SDKs.
GraphQL introspection is built-in; add examples.
Provide code samples in 3+ languages.
Frequently Asked Questions
Should I always use REST?+
For public APIs, usually yes. For internal complex clients, GraphQL or tRPC often win.
Is GraphQL dying?+
No — but the hype cycle has cooled. GraphQL is still a great fit for specific problems, especially mobile.
What about gRPC?+
Excellent for service-to-service in polyglot backends. Overkill for most web-facing APIs.
Do I need OpenAPI?+
For any REST API you expose, yes. Auto-generated docs + client SDKs pay back the investment quickly.
Which auth is safest for browser apps?+
HttpOnly session cookies with CSRF protection. JWT in localStorage is a common but weaker pattern.