Mở đầu — vì sao bài này quan trọng
Trong vai trò Business Analyst, sẽ có rất nhiều lần bạn được mời vào một cuộc họp design review, đặt trước mặt là một bản OpenAPI spec dài 40 trang, và câu hỏi quen thuộc vang lên: "Anh/chị BA xem giúp spec này ổn chưa để team dev bắt đầu code nhé?". Đây là khoảnh khắc quyết định giá trị của một BA giỏi. Nếu bạn chỉ đọc lướt qua phần mô tả và gật đầu, bạn đã bỏ lỡ cơ hội phát hiện những lỗi thiết kế sẽ tốn hàng tuần để sửa sau khi đã code xong.
Cả khóa học này đã trang bị cho bạn từng mảnh kiến thức riêng lẻ: cấu trúc HTTP, status code, pagination, versioning, error response, idempotency, authentication... Bài 56 chính là nơi lắp ráp tất cả những mảnh đó thành một chiếc kính lúp — một checklist có hệ thống để bạn review bất kỳ API spec nào một cách tự tin, nhất quán và không bỏ sót.
Điểm mấu chốt cần hiểu: BA review spec không phải để bắt lỗi developer, mà để bảo vệ ba thứ — trải nghiệm của hệ thống tiêu dùng API (consumer), tính nhất quán dài hạn của sản phẩm, và sự khớp nối giữa API với nghiệp vụ thực tế. Một API "chạy được" nhưng thiết kế tệ sẽ khiến đối tác tích hợp than phiền, đội support ngập trong ticket, và mỗi tính năng mới đều phải vá víu. BA là người duy nhất trong phòng nhìn API bằng con mắt nghiệp vụ thay vì con mắt kỹ thuật thuần túy — và đó chính là siêu năng lực của bạn.
Khái niệm cốt lõi
Một checklist review API spec hiệu quả nên được chia thành các nhóm logic. Dưới đây là khung 7 nhóm mà bạn có thể dùng đi dùng lại cho mọi dự án.
1. Resource & URL — Tài nguyên và đường dẫn
Đây là tầng dễ nhìn ra lỗi nhất và cũng là nơi BA tạo tác động lớn nhất.
- [ ] Resource là danh từ, không phải động từ. Đúng:
/users,/orders. Sai:/createUser,/getOrderById. Hành động đã được thể hiện qua HTTP method rồi (POST tạo, GET đọc), không cần lặp lại trong URL. - [ ] Collection dùng số nhiều.
/orderschứ không phải/order. Nhất quán toàn bộ API. - [ ] Phân cấp tài nguyên rõ ràng. Tài nguyên con nằm dưới cha:
/orders/{orderId}/items/{itemId}. Tránh lồng quá sâu (quá 2 cấp thường là dấu hiệu thiết kế sai). - [ ] Không nhét động từ nghiệp vụ vào path tùy tiện. Với hành động không map gọn vào CRUD (ví dụ "duyệt đơn hàng"), pattern thường dùng là
POST /orders/{id}/approvalhoặcPOST /orders/{id}:approve— phải nhất quán trong cả spec. - [ ] Path dùng kebab-case hay không có ký tự lạ.
/shipping-addresses, tránh/shippingAddressestrên URL.
2. HTTP Methods & Status Codes — Phương thức và mã trạng thái
- [ ] Method dùng đúng ngữ nghĩa. GET không được thay đổi dữ liệu; PUT để thay thế toàn bộ, PATCH để cập nhật một phần; DELETE để xóa.
- [ ] Status code phản ánh đúng kết quả. 201 khi tạo mới thành công (không phải 200 chung chung), 204 khi xóa không trả body, 400 cho lỗi đầu vào, 401 chưa xác thực, 403 không có quyền, 404 không tìm thấy, 409 xung đột, 422 dữ liệu hợp lệ về cú pháp nhưng sai nghiệp vụ.
- [ ] Idempotency được đảm bảo. GET, PUT, DELETE phải idempotent. Với POST tạo tài nguyên quan trọng (đặc biệt là thanh toán), spec có hỗ trợ idempotency key không?
3. Request & Response Body — Cấu trúc dữ liệu
- [ ] Tên field nhất quán một kiểu naming. Chọn camelCase hoặc snake_case rồi giữ nguyên toàn bộ. Không lẫn
userIdchỗ này,created_atchỗ kia. - [ ] Kiểu dữ liệu rõ ràng và đúng chuẩn. Tiền tệ là số nguyên (đơn vị nhỏ nhất) hay decimal? Thời gian có theo ISO 8601 với timezone không (
2026-06-27T10:00:00+07:00)? - [ ] Field bắt buộc vs tùy chọn được đánh dấu rõ.
requiredtrong schema phải khớp với nghiệp vụ thực tế. - [ ] Không trả dữ liệu nhạy cảm dư thừa. Spec có vô tình expose
password_hash, số CMND/CCCD đầy đủ, hay token nội bộ không?
4. Error Response — Thiết kế lỗi
- [ ] Cấu trúc lỗi nhất quán trên toàn API. Mọi lỗi nên có cùng một "hình dạng": ví dụ
{ "error": { "code": "...", "message": "...", "details": [...] } }. - [ ] Có error code dạng máy đọc được. Để client xử lý logic theo
codethay vì parse chuỗimessage(vì message có thể đổi). - [ ] Message đủ hữu ích nhưng không lộ thông tin nhạy cảm (không trả stack trace, không lộ cấu trúc database).
5. Pagination, Filtering, Sorting
- [ ] Mọi collection có khả năng trả về số lượng lớn đều phải có pagination. Endpoint
GET /transactionsmà không phân trang là một quả bom hẹn giờ. - [ ] Cơ chế phân trang được nêu rõ (offset/limit, page-based, hay cursor) và nhất quán.
- [ ] Filtering và sorting được chuẩn hóa. Ví dụ
?status=paid&sort=-createdAt.
6. Authentication, Authorization & Security
- [ ] Mỗi endpoint nêu rõ yêu cầu xác thực. Public hay cần token? Scope/quyền nào được phép?
- [ ] Cơ chế auth nhất quán (Bearer token, API key...) và đúng chuẩn đã thống nhất.
- [ ] Có rate limiting được mô tả với endpoint nhạy cảm.
7. Versioning, Documentation & Consistency
- [ ] Chiến lược versioning rõ ràng (
/v1/...hoặc qua header) và nhất quán. - [ ] Mỗi endpoint có mô tả, ví dụ request/response. OpenAPI có đủ
summary,description,example. - [ ] Toàn spec nhất quán về phong cách — đây là tiêu chí "vô hình" nhưng quan trọng nhất: một API tốt là một API mà sau khi học 3 endpoint, bạn đoán đúng endpoint thứ 4.
Tình huống thực tế
Ví dụ 1: Sàn TMĐT "ChợViệt" và bản spec lẫn lộn động từ
Một startup TMĐT giả định tên ChợViệt chuẩn bị mở API cho 200 nhà bán hàng tích hợp hệ thống kho của họ. Linh — BA của dự án — được giao review spec do team backend viết. Cô mở file OpenAPI và nhận ra ngay sự hỗn loạn: trong cùng một spec tồn tại POST /createProduct, GET /products, POST /product/update, và GET /getProductDetail/{id}. Bốn endpoint, ba phong cách đặt tên khác nhau.
Linh không chỉ ghi "tên xấu" rồi bỏ qua. Cô lập một bảng so sánh, chỉ ra rằng nếu nhà bán hàng phải nhớ bốn quy ước khác nhau, chi phí tích hợp của mỗi đối tác sẽ tăng và team support sẽ nhận thêm ticket. Cô đề xuất chuẩn hóa về resource-based: POST /products, GET /products, PATCH /products/{id}, GET /products/{id}. Cô cũng phát hiện POST /product/update đang dùng để cập nhật một phần nhưng lại được đặt tên gây hiểu là thay thế toàn bộ — và đề xuất tách rõ PATCH (cập nhật một phần) khỏi PUT (thay thế).
Bài học: Lỗi naming không phải "chuyện nhỏ thẩm mỹ". Với API mở cho đối tác bên ngoài, mỗi sự thiếu nhất quán đều là chi phí thật cho hàng trăm tích hợp. BA dịch lỗi kỹ thuật thành ngôn ngữ chi phí kinh doanh là cách thuyết phục team dev hiệu quả nhất.
Ví dụ 2: Fintech và endpoint giao dịch thiếu pagination
Một công ty fintech tại TP.HCM xây API cho ứng dụng ví điện tử. Spec có endpoint GET /wallets/{id}/transactions trả về toàn bộ lịch sử giao dịch của một ví. Trong giai đoạn demo với dữ liệu test 20 giao dịch, mọi thứ chạy mượt. Nhưng BA tên Tuấn đặt một câu hỏi nghiệp vụ đơn giản trong buổi review: "Một ví dùng 2 năm thì có bao nhiêu giao dịch?". Câu trả lời: có thể vài chục nghìn.
Tuấn ghi vào checklist: endpoint này thiếu pagination — vi phạm mục 5. Anh chỉ ra hai rủi ro cụ thể: response có thể nặng vài MB làm app mobile lag và tốn data của người dùng; và database query không giới hạn có thể làm chậm cả hệ thống khi nhiều người mở lịch sử cùng lúc. Anh đề xuất cursor-based pagination (phù hợp dữ liệu giao dịch thêm liên tục và cần ổn định thứ tự), kèm filter theo khoảng thời gian ?from=...&to=.... Đồng thời anh soi thêm tầng bảo mật: endpoint này có kiểm tra rằng người gọi đúng là chủ ví {id} không, hay chỉ cần token hợp lệ là xem được ví của bất kỳ ai? Hóa ra spec chưa nêu rõ phần authorization này — một lỗ hổng nghiêm trọng được phát hiện ngay từ giai đoạn spec.
Bài học: Sức mạnh lớn nhất của BA khi review API là đặt câu hỏi nghiệp vụ về dữ liệu thực tế, không phải dữ liệu demo. "Thực tế cái này có bao nhiêu bản ghi?", "Ai được phép xem?" — những câu hỏi đó lộ ra lỗ hổng mà người chỉ nhìn code dễ bỏ qua.
Ví dụ 3: Tích hợp đối tác logistics và error response hỗn loạn
Một doanh nghiệp bán lẻ tích hợp API của một đối tác giao vận để tạo đơn vận chuyển. BA tên Hà review spec đối tác và thử map các tình huống lỗi. Cô phát hiện: khi địa chỉ sai, API trả 400 với body "Invalid address"; khi hết hàng tại kho, trả 200 nhưng trong body có chữ "failed"; khi token sai, trả 403 với HTML thay vì JSON. Ba kiểu lỗi, ba hình dạng response hoàn toàn khác nhau.
Hà lập danh sách mọi trường hợp lỗi nghiệp vụ có thể xảy ra (sai địa chỉ, quá tải khu vực, gói hàng vượt kích thước, tài khoản hết hạn mức) và yêu cầu đối tác cung cấp: một cấu trúc lỗi thống nhất dạng JSON, một bộ error code ổn định để hệ thống của cô tự động xử lý, và quan trọng nhất — lỗi nghiệp vụ "hết hàng" phải trả status code lỗi (ví dụ 422) chứ không phải 200. Vì nếu trả 200, hệ thống của cô sẽ tưởng đơn tạo thành công và khách hàng sẽ chờ một gói hàng không bao giờ tới.
Bài học: Error response design là nơi BA bảo vệ trải nghiệm cuối của khách hàng. Một status code sai một con số có thể biến thành một đơn hàng "ma" và một khách hàng giận dữ. Khi review spec của đối tác bên ngoài (mà bạn không kiểm soát code), checklist này càng quan trọng vì bạn chỉ có duy nhất bản spec để dựa vào.
Hướng dẫn từng bước
Khi nhận một API spec để review, hãy đi theo quy trình sau thay vì đọc tuần tự từ trên xuống:
- Đọc tổng quan để nắm "ngôn ngữ" của API. Lướt qua 3-4 endpoint đầu để hiểu quy ước đặt tên, kiểu naming field, cách versioning. Ghi nhận phong cách "mặc định" của spec này.
- Lập bảng resource. Liệt kê tất cả tài nguyên và các thao tác (method) trên chúng. Bảng này lập tức cho thấy chỗ thiếu nhất quán — ví dụ một resource có đủ CRUD nhưng resource khác lại thiếu DELETE mà nghiệp vụ cần.
- Chạy qua từng nhóm trong checklist 7 mục. Đừng dựa vào trí nhớ. Mở checklist ra và tick từng dòng cho từng endpoint. Tốc độ sẽ tăng nhanh sau vài endpoint vì nhiều lỗi lặp lại.
- Đối chiếu với nghiệp vụ và user story. Với mỗi endpoint, hỏi: "Endpoint này phục vụ luồng nghiệp vụ nào? Dữ liệu trả về có đủ cho màn hình/tính năng đó không? Có field thừa không?". Đây là phần mà chỉ BA làm được tốt nhất.
- Soi các trường hợp biên (edge case). Dữ liệu rỗng, danh sách rất dài, người dùng không có quyền, gọi lại lần hai (idempotency), giá trị null. Mỗi edge case là một dòng câu hỏi cho team dev.
- Phân loại phát hiện theo mức độ. Chia thành: Blocker (phải sửa trước khi code — ví dụ lỗ hổng authorization), Major (nên sửa — thiếu pagination), Minor (cải thiện — naming chưa nhất quán). Việc phân loại giúp cuộc họp tập trung và team dev biết ưu tiên.
- Viết feedback có đề xuất, kèm lý do nghiệp vụ. Đừng chỉ nói "cái này sai". Hãy viết "Endpoint X thiếu pagination → rủi ro response nặng khi dữ liệu lớn → đề xuất cursor-based pagination". Lý do nghiệp vụ là thứ thuyết phục.
Lỗi thường gặp & mẹo
Lỗi 1 — Review như một developer thuần túy. Nhiều BA cố soi chi tiết kỹ thuật (kiểu index database, thuật toán) và bỏ quên thế mạnh thật sự: liên kết API với nghiệp vụ. Mẹo: với mỗi endpoint, luôn quay về câu hỏi "tính năng nào dùng cái này và nó có phục vụ đủ không?".
Lỗi 2 — Chỉ đọc phần mô tả, bỏ qua schema và example. Phần description thường được viết đẹp, nhưng lỗi nằm trong schema và ví dụ. Mẹo: luôn đọc example request/response thật kỹ — chúng phơi bày sự thật về kiểu dữ liệu và naming.
Lỗi 3 — Bỏ qua tính nhất quán xuyên endpoint. Soi từng endpoint riêng lẻ có thể thấy mọi thứ ổn, nhưng đặt cạnh nhau mới lộ ra userId ở chỗ này thành user_id ở chỗ khác. Mẹo: review theo chiều ngang (cùng một tiêu chí qua tất cả endpoint) ít nhất một lượt, không chỉ chiều dọc.
Lỗi 4 — Đưa feedback dạng phán xét thay vì cộng tác. "Spec này tệ" làm dev phòng thủ. Mẹo: dùng ngôn ngữ "tôi lo rằng...", "nếu trường hợp X xảy ra thì...", và luôn kèm đề xuất.
Lỗi 5 — Quên dữ liệu nhạy cảm và bối cảnh pháp lý. Tại Việt Nam, dữ liệu cá nhân (CCCD, số điện thoại, địa chỉ) được điều chỉnh bởi Nghị định bảo vệ dữ liệu cá nhân. Mẹo: thêm một dòng cố định vào checklist — "endpoint này có trả PII không, có cần thiết không?".
Mẹo vàng: Biến checklist này thành một template tái sử dụng (Google Sheet hoặc Confluence) trong tổ chức của bạn. Sau vài dự án, nó trở thành tài sản chung và nâng chuẩn cho cả team — đây là cách một BA tạo ảnh hưởng vượt ra ngoài một dự án đơn lẻ.
Bài tập thực hành
Bài 1 — Soi lỗi resource & URL. Cho danh sách endpoint sau, tìm tất cả vi phạm và viết lại đúng chuẩn:
POST /createOrder, GET /order/{id}, POST /orders/{id}/cancelOrder, GET /getAllOrdersForUser/{userId}.
Bài 2 — Đặt câu hỏi nghiệp vụ. Cho endpoint GET /products của một sàn TMĐT trả về toàn bộ sản phẩm dạng mảng phẳng. Viết ra ít nhất 4 câu hỏi nghiệp vụ bạn sẽ đặt trong buổi review (gợi ý: số lượng dữ liệu, lọc, sắp xếp, hiển thị trên màn hình nào).
Bài 3 — Phân loại mức độ. Cho ba phát hiện sau, hãy gán nhãn Blocker / Major / Minor và giải thích ngắn: (a) endpoint chuyển tiền không có idempotency key; (b) field thời gian trả về không có timezone; (c) một endpoint dùng created_at còn các endpoint khác dùng createdAt.
Bài 4 — Viết feedback chuẩn. Chọn một phát hiện ở Bài 3 và viết một đoạn feedback hoàn chỉnh theo công thức: vấn đề → rủi ro nghiệp vụ → đề xuất giải pháp.
Tóm tắt
Review API spec là một trong những kỹ năng "có giá" nhất của BA kỹ thuật, vì nó phát hiện vấn đề ở giai đoạn rẻ nhất để sửa — trước khi một dòng code được viết. Hãy ghi nhớ:
- Dùng khung 7 nhóm: Resource & URL → Methods & Status → Body → Error → Pagination/Filter/Sort → Auth & Security → Versioning/Docs/Consistency.
- Sức mạnh riêng của BA là liên kết API với nghiệp vụ thực tế và đặt câu hỏi về dữ liệu thật, quyền truy cập, và trải nghiệm khách hàng — chứ không sa vào chi tiết kỹ thuật thuần.
- Tính nhất quán xuyên suốt là tiêu chí quan trọng nhất nhưng dễ bị bỏ sót; hãy review theo chiều ngang.
- Phát hiện cần được phân loại theo mức độ và feedback kèm lý do nghiệp vụ + đề xuất, không phán xét.
- Biến checklist thành template tái sử dụng để nâng chuẩn cho cả tổ chức.