API design 2026: REST vs GraphQL vs tRPC — chọn style nào cho dự án VN nhỏ?

Năm 2026, không có câu trả lời 'API style tốt nhất'. Mỗi style fit scenario khác nhau. Quyết định sai có thể mất 2-3 tháng migrate sau này. Bài này giúp bạn chọn đúng từ đầu.

REST (Representational State Transfer) là style API phổ biến nhất năm 2026 — ~76% API production theo Postman State of API 2025. Dùng HTTP method + resource URL (GET /users/123, POST /orders).

Ưu điểm: - Universal: mọi ngôn ngữ/framework hỗ trợ HTTP client. Public API mobile/IoT dùng REST chuẩn. - HTTP caching native: ETag, Cache-Control, CDN cache response dễ. Giảm server load rõ rệt. - Debugging dễ: chỉ cần browser DevTools hoặc Postman xem request/response. - OpenAPI 3.1 spec (formerly Swagger): auto-generate docs + client SDK cho 30+ ngôn ngữ. - Security model rõ: OAuth 2.1, JWT, API key, rate limit chuẩn.

Nhược điểm: - Over-fetching / under-fetching: mobile app cần 3 field của User nhưng REST trả full object 20 field. Waste bandwidth. Hoặc cần 3 API call lấy user + orders + addresses. - Versioning pain: breaking change → tạo v2, maintain v1 cho backward compat. Phức tạp. - No type safety end-to-end: frontend dev phải tự sync type với backend (hoặc code gen từ OpenAPI). - Verbose cho CRUD lặp: mỗi resource cần 5 endpoint (GET list, GET one, POST, PATCH, DELETE).

Khi nào chọn REST: - Public API cho 3rd-party integration (Stripe, Shopify, tất cả dùng REST). - Team BE/FE tách biệt, dùng ngôn ngữ khác nhau. - API cần SEO/crawl — Google bot crawl REST endpoints dễ. - Team mới, cần hiring — REST dev dễ tìm nhất. - Legacy integration — ERP, CRM cũ chỉ hỗ trợ REST.

Framework/tool 2026: - Node.js: Express (simple), Fastify (faster), NestJS (opinionated). - Python: FastAPI (auto OpenAPI + async), Django REST Framework. - Go: Gin, Echo, Chi. - Documentation: Swagger UI / Redoc / Scalar (mới 2024, đẹp hơn Swagger). - Test: Postman (xem hướng dẫn).

GraphQL (Facebook, 2015) là query language cho API. Client gửi query mô tả data cần → server trả chính xác data đó, không thừa không thiếu.

Example: ```graphql query { user(id: "123") { name email orders(last: 5) { total status } } } ``` Server trả JSON đúng structure trên. Không cần nhiều request.

Ưu điểm: - Giải quyết over-fetching: client specify fields, API trả đúng. Mobile app tiết kiệm bandwidth. - Single endpoint: /graphql handle tất cả query/mutation. Đơn giản hơn nhiều REST endpoint. - Strongly typed schema: tool như GraphQL Codegen generate TypeScript types tự động. - Fragments reusable: component share UI fragment query, composable. - Subscriptions real-time: built-in WebSocket support cho real-time data. - Multi-data-source aggregation: 1 GraphQL query fetch data từ nhiều service backend (REST + DB + 3rd-party).

Nhược điểm: - HTTP caching phức tạp: mọi query POST /graphql → browser/CDN khó cache. Cần Apollo Client cache hoặc GraphQL-specific CDN. - N+1 query problem: resolver nested (User → Orders → Items) có thể gây hàng trăm query DB. Cần DataLoader pattern. - Learning curve cao: schema, resolver, federation, cache — mất 2-4 tuần onboarding. - Authorization phức tạp: mỗi field có thể cần permission check riêng. - File upload awkward: native GraphQL không support, phải dùng multipart spec extension.

Khi nào chọn GraphQL: - Mobile app với nhiều view khác nhau — mỗi view query data khác. - Backend aggregate nhiều microservice — GraphQL gateway đứng trước cluster service. - Team có frontend heavy, muốn tự control data fetching. - Iteration rapid — thêm field không cần version API.

Framework 2026: - Node.js: Apollo Server, GraphQL Yoga, Mercurius (Fastify-based). - Python: Strawberry, Graphene. - Go: gqlgen. - Client: Apollo Client (React), URQL (lightweight), Relay (Meta). - Schema-first vs code-first: 2026 hầu hết dùng code-first (schema generate từ code).

tRPC (Alex Johansson, 2020) là RPC framework cho TypeScript — không có schema definition riêng, type suy ra từ code TypeScript. Call API y hệt call function.

Example: ```ts // server/routers/user.ts export const userRouter = t.router({ getById: t.procedure .input(z.object({ id: z.string() })) .query(async ({ input }) => { return await db.user.findUnique({ where: { id: input.id } }); }), }); // client const user = await trpc.user.getById.query({ id: "123" }); // user fully typed, autocomplete, type error at compile time ```

Ưu điểm: - Type safety end-to-end: rename field trong DB → TypeScript báo lỗi tất cả client code dùng field đó. Zero runtime type error. - Zero code gen: không cần chạy npm run codegen sau thay đổi schema. - DX xuất sắc: autocomplete API ngay trong IDE như gọi function local. - Integrate với React Query: caching, optimistic update, retry built-in. - Small bundle size: ~8KB client, không có overhead GraphQL runtime. - Subscription support real-time qua WebSocket.

Nhược điểm: - TypeScript only: server + client cùng TypeScript mono/shared repo. Không dùng được cho Python/Go backend. - Không public API friendly: tRPC không fit cho expose API ra ngoài 3rd-party (không OpenAPI spec natively). - Mobile native (Swift/Kotlin) không dùng được — cần wrap REST. - Monorepo required hoặc share types qua npm package — setup non-trivial. - Ecosystem nhỏ hơn REST/GraphQL — community 2026 growing nhưng chưa mature.

Khi nào chọn tRPC: - Fullstack TypeScript: Next.js + API routes, Remix, Nuxt Nitro, Astro. - Solo dev hoặc team nhỏ < 10 người cùng TypeScript. - Startup MVP ship fast — tRPC tiết kiệm 30-50% thời gian dev API. - Không cần public API — dùng internal FE + BE.

Framework 2026: - tRPC v11 (2025): performance tốt hơn, better error handling, experimental HTTP streaming. - Adapter: Next.js App Router, Fastify, Express, AWS Lambda. - Alternative: Hono RPC (lighter, Hono framework), Bun's elysia RPC.

SaaS B2B internal tools + dashboard: - Solo/team nhỏ TS fullstack → tRPC + Next.js. - Team BE/FE split → REST OpenAPI + React + Tanstack Query.

E-commerce + mobile app (iOS + Android + Web): - GraphQL qua Apollo Server — mobile app fetch đúng data cho từng screen. - Alternative: REST + BFF (Backend-for-Frontend pattern) — fit nếu team không quen GraphQL.

Public API cho partner/3rd-party: - REST bắt buộc. OpenAPI 3.1 spec + Postman collection. - GraphQL/tRPC không phù hợp — partner dev không dùng được universally.

Real-time chat / collaboration app: - GraphQL Subscriptions hoặc tRPC Subscriptions cho typing indicator. - Plus WebSocket (Socket.IO, native ws) cho message delivery.

Microservice backend với multiple frontend (web + mobile + admin panel): - GraphQL Federation — Apollo Federation/Hasura stitching nhiều service thành 1 schema. - Alternative: REST + API Gateway (Kong, Tyk) pattern.

Startup MVP 1-2 người dev: - tRPC + Next.js — ship MVP 2-4 tuần thay vì 2-3 tháng. - Switch sang REST sau khi có traction + cần public API.

Không bắt buộc chọn 1 style duy nhất. Nhiều dự án dùng kết hợp:

Pattern 1: REST + GraphQL: - REST cho public API (Stripe-style). - GraphQL gateway cho internal mobile app aggregate data.

Pattern 2: tRPC + REST: - tRPC cho internal app (admin dashboard, web app) — solo dev ship fast. - REST cho webhook inbound + mobile app — universal.

Pattern 3: GraphQL + REST: - GraphQL primary cho frontend. - REST fallback cho file upload, server-sent events, 3rd-party integration.

Migration REST → GraphQL thường khó (rewrite resolver + client queries). Migration REST → tRPC còn khó hơn (cần rewrite tất cả handler với context TypeScript). Migration tRPC → REST dễ nhất — tRPC có OpenAPI adapter (trpc-openapi) generate REST endpoint từ tRPC router, phục vụ public API trong khi vẫn giữ tRPC cho internal.

Để test API bất kỳ style nào (REST, GraphQL qua HTTP), dùng Postman — tool phổ biến nhất cho API testing, hỗ trợ automation + collaboration. Xem hướng dẫn Postman chi tiết trong bài /phan-mem/postman.