API Design RESTful: 10 Quy Tắc Thiết Kế API Chuyên Nghiệp
API là hợp đồng giữa frontend và backend, giữa service và service, giữa bạn và developer bên thứ 3. API design tệ → breaking changes liên tục, integration bugs, developer frustration. API design tốt → stable, predictable, self-documenting, dễ extend mà không break backward compatibility. Theo Postman State of APIs Report 2024, 73% developers nói API quality ảnh hưởng trực tiếp đến productivity — và 52% từng bỏ integration với service vì API documentation quá kém. Bài viết này tổng hợp 10 quy tắc từ kinh nghiệm thiết kế 200+ endpoints cho xongviec.vn platform, kết hợp industry best practices 2025.
REST vs GraphQL vs gRPC: Khi Nào Dùng Gì?
REST là lựa chọn mặc định cho hầu hết APIs: đơn giản, dùng HTTP methods chuẩn, caching dễ dàng qua HTTP headers, ecosystem rộng lớn. GraphQL phù hợp khi frontend cần flexibility cao — clients query đúng data cần, tránh over-fetching (lấy thừa) và under-fetching (lấy thiếu). Nhưng cần invest vào schema design và query complexity analysis. gRPC cho service-to-service communication trong microservices — HTTP/2, binary Protocol Buffers, latency thấp, strong typing. Xu hướng 2025: REST cho external APIs, gRPC cho internal services, GraphQL cho complex UI applications. xongviec.vn sử dụng REST cho tất cả 200+ endpoints — đơn giản, dễ document, dễ test.
10 Quy Tắc Thiết Kế API Production-Ready
① Nouns, Not Verbs
URL dùng noun (danh từ) mô tả resource: /api/tasks, /api/users/123. HTTP method là verb: GET (đọc), POST (tạo), PUT (update toàn
bộ), PATCH (update 1 phần), DELETE (xóa). Ví dụ sai: GET /api/getTaskById?id=123 — redundant vì GET đã là "get". Đúng: GET /api/tasks/123. Nguyên tắc: developer đọc URL biết ngay đang thao tác với
resource nào, HTTP method cho biết thao tác gì.
② Consistent Naming Convention
Chọn 1 convention và giữ nguyên toàn bộ API: kebab-case (/task-comments) cho URL paths, camelCase (createdAt, taskId) cho JSON properties. Luôn dùng plural nouns cho collections: /tasks không phải /task. xongviec.vn convention:
kebab-case URLs, camelCase JSON body, lowercase với hyphens cho
query params. Inconsistency = confusion cho consumers — nhất là
khi có API gateway aggregating nhiều services.
③ Versioning Từ Ngày Đầu
Luôn version API ngay từ release đầu tiên: /api/v1/tasks. Khi cần breaking change → tạo /api/v2/tasks, giữ
v1 deprecated tối thiểu 6-12 tháng (theo industry standard). 3
strategies phổ biến:
URI versioning (/v1/) — đơn giản
nhất, visible;
Header versioning (Accept: application/vnd.bcf.v2+json) — clean URLs; Query param (?version=2) — dễ test. xongviec.vn dùng URI versioning vì clarity cho
developers. Giới hạn 2-3 active versions để tránh maintenance
overhead.
④ Pagination Cho Mọi Collection
Không bao giờ return toàn bộ records — 10,000 rows response =
slow, memory heavy, UX tệ. Default: ?page=1&pageSize=20. Response metadata:
totalCount, pageCount, currentPage,
hasNextPage. xongviec.vn: max pageSize = 100, default
= 20. Cho infinite scroll / real-time feeds: cursor-based pagination
(?cursor=eyJpZCI...&limit=20) — performance tốt hơn
offset pagination khi data thay đổi thường xuyên (không bị skip
hoặc duplicate items).
⑤ Consistent Error Format
Mọi error response dùng cùng JSON structure: {"statusCode": 400, "message": "...", "errors": [...]}. HTTP status codes đúng ngữ nghĩa: 400 (bad request — input
sai), 401 (unauthenticated — chưa login), 403 (forbidden — đã
login nhưng không có quyền), 404 (not found), 409 (conflict —
duplicate), 422 (validation error), 429 (rate limited), 500
(server error). KHÔNG dùng 200 OK cho errors — frontend
phải check body để biết success hay fail = anti-pattern.
⑥ Filtering, Sorting, Searching
Filter: ?status=in-progress&priority=high. Sort: ?sortBy=createdAt&sortOrder=desc. Search: ?search=bug+login. Tách riêng từng
concern, không gộp vào 1 parameter phức tạp. Whitelist allowed
sort fields để tránh SQL injection qua dynamic sorting.
xongviec.vn: mọi list endpoint hỗ trợ filter + sort + search +
pagination — kết hợp linh hoạt.
⑦ Idempotency
GET, PUT, DELETE phải idempotent — gọi 1 lần hay 10
lần cho cùng kết quả. POST tạo resource mới mỗi lần → nguy hiểm khi
network retry: user click "Create" 2 lần → 2 records trùng. Giải pháp:
X-Idempotency-Key: uuid trong request header. Server check:
key đã xử lý rồi → return cached response, chưa xử lý → xử lý và cache.
Stripe, PayPal đều dùng pattern này cho payment APIs — critical cho
financial transactions.
⑧ Rate Limiting
Protect API khỏi abuse và DDoS: 100 requests/phút/user cho general
endpoints, 10 requests/phút cho expensive operations (reports,
exports). Response headers thông báo client: X-RateLimit-Limit: 100, X-RateLimit-Remaining: 42, X-RateLimit-Reset: 1703980800. Vượt limit → 429 Too Many Requests + Retry-After header.
Algorithms phổ biến: Token Bucket (burst-friendly), Sliding Window (smooth
distribution). Rate limit per API key, per IP, hoặc per user — tùy use
case.
⑨ OpenAPI Documentation
Mọi API phải có OpenAPI (Swagger) spec — là "single source of
truth" cho API contract. Developer đọc docs, try endpoints
interactive, generate client SDKs mà không cần hỏi backend team.
Design-first approach: viết OpenAPI spec trước, review, rồi mới
implement. Auto-generate docs trong CI/CD pipeline. xongviec.vn:
Swagger UI tại /swagger cho mọi environment, bao gồm request/response
examples cho mọi endpoint.
⑩ Nested Resources Đúng Mức
Max 2 levels nesting: /projects/123/tasks — rõ ràng, dễ
hiểu.
/projects/123/tasks/456/comments/789/reactions — quá sâu,
URL dài, khó maintain, khó cache. Dùng flat endpoints kèm filter: /reactions?commentId=789. Nested resources nên thể hiện ownership relationship rõ ràng
(task belongs to project), không phải mọi association.
Security-First API Design
Bảo mật phải được bake vào API design, không phải add-on sau cùng. Authentication: OAuth 2.0 + JWT tokens cho stateless auth, refresh token rotation
cho security.
Authorization: RBAC (Role-Based Access Control) cho
mọi endpoint — check permissions trước khi xử lý business logic. Input validation: validate tất cả inputs server-side, không tin client. HTTPS only: reject HTTP requests, dùng HSTS headers. CORS:
whitelist specific origins, không dùng Access-Control-Allow-Origin: * trong production. API Gateway (Kong, AWS API Gateway) centralize authentication,
rate limiting, và monitoring cho tất cả services.