Mở đầu — vì sao bài này quan trọng
Bạn là một developer đang chuyển sang BA, và đây có lẽ là một trong những bài học khiến bạn cảm thấy "về nhà" nhất. Bởi vì API — thứ mà nhiều BA thuần kinh doanh phải vật lộn để hiểu — thì với bạn đã là cơm bữa. Bạn đã từng gọi REST API, đọc JSON response, debug status code 401, viết Postman collection. Đây chính là lúc nền tảng kỹ thuật của bạn trở thành vũ khí cạnh tranh thật sự.
Nhưng có một điều quan trọng bạn cần nhận ra sớm: viết API documentation với vai trò BA không giống với viết API với vai trò developer. Khi còn là dev, bạn document API để đồng nghiệp dev khác tích hợp. Khi là BA, bạn document API để diễn giải một thỏa thuận giữa các bên — giữa team frontend và backend, giữa hệ thống của công ty bạn và đối tác bên ngoài, giữa kỳ vọng nghiệp vụ và hành vi kỹ thuật. API spec của BA không chỉ trả lời "endpoint này hoạt động thế nào", mà còn "vì sao nó tồn tại, ai dùng nó, và quy tắc nghiệp vụ nào nằm phía sau".
Trong thực tế dự án ở Việt Nam — đặc biệt các dự án tích hợp với ngân hàng, cổng thanh toán (VNPay, Momo, ZaloPay), hay đối tác offshore Nhật/Mỹ — API spec thường là hợp đồng kỹ thuật mà cả hai bên ký vào. Một BA viết API spec tốt sẽ giảm hàng chục buổi họp làm rõ, tránh việc team backend build sai, và rút ngắn vòng tích hợp từ vài tuần xuống vài ngày. Bài này dạy bạn cách làm điều đó một cách chuẩn mực.
Khái niệm cốt lõi
API spec là gì dưới góc nhìn BA
Một API (Application Programming Interface) đơn giản là cách hai phần mềm "nói chuyện" với nhau. Với BA, một bản API specification là tài liệu mô tả hợp đồng giao tiếp đó: client gửi gì đi, server trả gì về, và cái gì xảy ra khi có lỗi. Bạn không cần viết code để tạo spec — nhưng bạn cần mô tả đủ chính xác để developer hai phía có thể tự build mà không phải đoán.
Điểm khác biệt cốt lõi so với khi bạn còn là dev: BA chịu trách nhiệm đảm bảo spec phản ánh đúng yêu cầu nghiệp vụ. Ví dụ, khi field phoneNumber trong API đăng ký người dùng — ai quyết định nó bắt buộc hay không, định dạng +84 hay 0, có cho phép số cố định không? Đó là quyết định nghiệp vụ, và BA là người chốt nó trước khi nó thành dòng trong spec.
OpenAPI / Swagger — chuẩn công nghiệp
Khi nói về document REST API một cách chuẩn mực, gần như cả thế giới dùng OpenAPI Specification (tên cũ là Swagger). Đây là một định dạng có cấu trúc, viết bằng YAML hoặc JSON, mô tả toàn bộ API: các endpoint, method (GET/POST/PUT/DELETE), tham số, cấu trúc dữ liệu, và các mã trả về.
Lý do OpenAPI thống trị là vì nó vừa cho người đọc, vừa cho máy đọc. Từ một file OpenAPI, công cụ có thể tự sinh ra:
- Tài liệu tương tác đẹp mắt (qua Swagger UI hoặc Redoc).
- Mock server để frontend test trước khi backend xong.
- Code client tự động (SDK) cho nhiều ngôn ngữ.
- Bộ test tự động kiểm tra API có đúng spec không.
Cấu trúc một endpoint trong tư duy BA
Mỗi endpoint, khi bạn mô tả, nên trả lời đầy đủ các "trường" (field) sau — đây là checklist tinh thần của một BA:
- Mục đích nghiệp vụ: Endpoint này phục vụ tính năng gì? (vd: "Tạo đơn hàng mới")
- HTTP Method + Path:
POST /api/v1/orders - Authentication: Cần token gì? Quyền gì? (vd: Bearer token, role
customer) - Request — Path/Query parameters: Tham số trên URL, vd
?status=pending. - Request — Body: Cấu trúc dữ liệu gửi lên, từng field kèm: kiểu dữ liệu, bắt buộc/tùy chọn, ràng buộc (độ dài, định dạng, giá trị cho phép), và mô tả nghiệp vụ.
- Response thành công: Status code (vd 201), cấu trúc dữ liệu trả về.
- Response lỗi: Các status code lỗi (400, 401, 404, 409, 422...) kèm thông điệp và nguyên nhân nghiệp vụ của từng lỗi.
- Business rules / validation: Quy tắc ẩn — vd "không cho tạo đơn nếu kho hết hàng" trả về 409.
- Ví dụ thực tế: Một cặp request/response mẫu có dữ liệu thật.
Các field BA hay bỏ sót
Theo kinh nghiệm, developer khi làm BA thường rất giỏi phần "happy path" (luồng thành công) nhưng hay quên ba thứ:
- Error cases có ý nghĩa nghiệp vụ — không chỉ "400 Bad Request" mà là "400 — số dư không đủ", "409 — email đã tồn tại".
- Ràng buộc nghiệp vụ trên field — vd
amounttối thiểu 10.000đ, tối đa 50.000.000đ/giao dịch theo quy định ngân hàng. - Idempotency và xử lý trùng lặp — đặc biệt với API thanh toán: nếu client gọi 2 lần do mạng chậm thì sao?
Tình huống thực tế
Ví dụ 1 — Tích hợp cổng thanh toán tại một startup e-commerce TP.HCM
Một startup bán mỹ phẩm online (giả định tên "BeautyBox") cần tích hợp cổng thanh toán VNPay. Minh, một backend dev vừa chuyển sang BA, được giao viết API spec cho luồng thanh toán nội bộ giữa frontend và backend của BeautyBox (trước khi backend gọi sang VNPay).
Ban đầu Minh viết spec rất kỹ phần happy path: POST /api/v1/payments/checkout, body gồm orderId, amount, paymentMethod. Response 200 trả về paymentUrl để redirect sang VNPay. Đẹp. Nhưng khi team backend build xong và QA test, hàng loạt vấn đề lộ ra: Điều gì xảy ra khi orderId đã được thanh toán rồi? Khi amount trong request không khớp với tổng đơn hàng trong DB? Khi user bấm thanh toán hai lần liên tiếp?
Minh ngồi lại, bổ sung spec với các response lỗi nghiệp vụ rõ ràng: 409 — ORDER_ALREADY_PAID, 422 — AMOUNT_MISMATCH, và quan trọng nhất là yêu cầu idempotency key trong header để chống double-charge. Anh cũng thêm bảng business rule: "amount phải bằng đúng tổng đơn hàng tại thời điểm tạo, làm tròn đến đồng, không nhận giá trị âm hoặc 0".
Bài học: Nền tảng dev giúp Minh viết phần kỹ thuật trôi chảy, nhưng giá trị BA thật sự nằm ở việc anh hỏi đúng những câu hỏi nghiệp vụ về error case. Một spec thiếu error case là spec chỉ làm xong một nửa.
Ví dụ 2 — Dự án offshore với khách hàng Nhật
Một công ty outsourcing ở Hà Nội (giả định "FSoft Partner") nhận dự án xây hệ thống quản lý kho cho khách hàng Nhật. Khách Nhật nổi tiếng tỉ mỉ và yêu cầu mọi API phải có spec OpenAPI 3.0 trước khi code. BA của dự án, chị Lan — xuất thân là dev Java — phụ trách viết spec cho 40+ endpoint.
Chị Lan dùng Stoplight Studio để soạn OpenAPI bằng giao diện trực quan, sau đó export ra file YAML đẩy lên Git để khách hàng review. Mỗi field trong request đều có mô tả song ngữ (Việt + tiếng Anh), kiểu dữ liệu rõ ràng, và ví dụ. Khách Nhật đặc biệt yêu cầu định nghĩa rõ các enum — vd field warehouseStatus chỉ nhận ACTIVE, INACTIVE, MAINTENANCE, không cho free text.
Kết quả: vòng review spec mất 3 tuần qua lại (vì khách rất kỹ), nhưng khi đã chốt, giai đoạn code và tích hợp gần như không có hiểu lầm. Khách Nhật dùng chính file OpenAPI để tự sinh mock server và viết test phía họ.
Bài học: Với khách offshore khó tính, API spec chuẩn OpenAPI không phải "nice to have" mà là điều kiện bắt buộc. Việc chị Lan biết dùng tool chuyên nghiệp (Stoplight) thay vì viết tay trong Word đã nâng tầm độ tin cậy của cả team. Một file OpenAPI máy đọc được luôn giá trị hơn 50 trang Word mô tả API.
Ví dụ 3 — API spec sai vì thiếu chi tiết validation
Tại một fintech ở Singapore mở rộng sang Việt Nam, một BA mới viết spec cho API xác thực OTP. Spec ghi: POST /api/v1/otp/verify, body { "otp": "string" }. Tưởng đơn giản. Nhưng vì spec không nói rõ: OTP dài bao nhiêu ký tự, hết hạn sau bao lâu, cho sai tối đa mấy lần trước khi khóa, nên team frontend và backend hiểu khác nhau hoàn toàn. Frontend cho nhập 4 số, backend mong 6 số. Backend khóa tài khoản sau 3 lần sai, frontend không hề hiển thị cảnh báo nào.
Khi go-live, khách hàng bị khóa tài khoản đột ngột mà không hiểu vì sao, support nhận hàng loạt khiếu nại. Truy nguyên ra: spec thiếu các ràng buộc và business rule quanh một field tưởng chừng tầm thường.
Bài học: Một field nhỏ như otp cũng cần spec đầy đủ: độ dài (6 số), TTL (5 phút), số lần thử (tối đa 5), hành vi khi vượt ngưỡng (khóa 30 phút, trả về 429 — TOO_MANY_ATTEMPTS). BA giỏi là người nhìn ra rằng độ phức tạp nằm ở ràng buộc, không phải ở số lượng field.
Hướng dẫn từng bước
Đây là quy trình thực tế để bạn viết một API spec chuẩn với vai trò BA:
Bước 1 — Xác định mục đích nghiệp vụ. Trước khi đụng vào kỹ thuật, viết một câu mô tả: endpoint này phục vụ user story nào, ai là người dùng, trong luồng nghiệp vụ nào. Nếu không trả lời được, bạn chưa nên viết spec.
Bước 2 — Định nghĩa contract cơ bản. Chọn HTTP method và path theo chuẩn REST (danh từ số nhiều cho resource: /orders, /users/{id}/orders). GET để đọc, POST để tạo, PUT/PATCH để sửa, DELETE để xóa. Đừng dùng động từ trong path kiểu /getOrders.
Bước 3 — Liệt kê request đầy đủ. Với mỗi field, ghi rõ 5 thứ: tên, kiểu dữ liệu (string/integer/boolean/array/object), bắt buộc hay không, ràng buộc (min/max, regex, enum), và mô tả nghiệp vụ. Đừng để field nào "trần trụi".
Bước 4 — Thiết kế response cho cả thành công và thất bại. Liệt kê đủ status code. Với mỗi lỗi, ghi rõ điều kiện kích hoạt và thông điệp. Hãy thống nhất một error format chung cho toàn API, vd: { "code": "AMOUNT_MISMATCH", "message": "...", "field": "amount" }.
Bước 5 — Bóc tách business rule. Đây là phần "đắt" nhất của BA. Liệt kê mọi quy tắc ẩn: ràng buộc liên field (ngày kết thúc phải sau ngày bắt đầu), điều kiện trạng thái (chỉ hủy được đơn ở trạng thái pending), giới hạn theo quy định (hạn mức giao dịch).
Bước 6 — Thêm ví dụ thật. Mỗi endpoint nên có ít nhất một cặp request/response mẫu với dữ liệu thực tế, không phải "string" hay "abc". Ví dụ thật giúp dev hiểu nhanh gấp nhiều lần mô tả văn xuôi.
Bước 7 — Chuyển sang OpenAPI và validate. Đưa nội dung vào Swagger Editor hoặc Stoplight. Công cụ sẽ báo lỗi cú pháp ngay. Khi file hợp lệ, render bằng Swagger UI để các bên cùng review giao diện đẹp.
Bước 8 — Review chéo với dev và tester. Mời backend, frontend, QA cùng đọc spec. Hỏi họ ba câu: "Có đủ để build không?", "Có chỗ nào mơ hồ không?", "Có error case nào tôi quên không?".
Lỗi thường gặp & mẹo
Lỗi 1 — Chỉ viết happy path. Đây là cái bẫy số một của dev-turned-BA. Mẹo: với mỗi endpoint, ép bản thân liệt kê tối thiểu 3 error case trước khi coi là xong.
Lỗi 2 — Field "trần", không ràng buộc. Viết amount: number rồi để đó. Mẹo: mỗi field hỏi "giá trị nào hợp lệ, giá trị nào không, và lỗi gì xảy ra nếu sai".
Lỗi 3 — Viết spec trong Word/Excel rời rạc. Word không validate được, dễ lỗi thời, không sinh được mock. Mẹo: ưu tiên OpenAPI lưu trong Git, version hóa cùng code. Word chỉ dùng để kèm bối cảnh nghiệp vụ.
Lỗi 4 — Sa đà vào kỹ thuật, quên nghiệp vụ. Vì bạn là dev, bạn dễ bị cuốn vào tối ưu performance, header chi tiết... mà quên rằng vai trò BA là đảm bảo spec phục vụ đúng business need. Mẹo: luôn mở đầu mỗi endpoint bằng một câu mục đích nghiệp vụ.
Lỗi 5 — Không thống nhất chuẩn naming và error. Mỗi endpoint một kiểu đặt tên, một format lỗi. Mẹo: viết một trang "API conventions" chung cho cả dự án (naming camelCase, ngày theo ISO 8601, error format thống nhất, phân trang chuẩn).
Mẹo vàng: Tận dụng lợi thế dev của bạn — hãy tự gọi thử API qua Postman khi backend làm xong, đối chiếu với spec. BA nào làm được điều này sẽ phát hiện sai lệch sớm hơn QA, và được cả team nể trọng.
Bài tập thực hành
Bài tập 1 — Viết spec cho một endpoint. Cho user story: "Là khách hàng, tôi muốn đặt lịch hẹn với mentor để được tư vấn." Hãy viết spec đầy đủ cho POST /api/v1/bookings: liệt kê tối thiểu 5 field request (kèm kiểu, bắt buộc, ràng buộc), response thành công 201, và ít nhất 3 error case có ý nghĩa nghiệp vụ (vd: mentor đã kín lịch, thời gian trong quá khứ, user chưa xác thực).
Bài tập 2 — Tìm lỗ hổng trong spec. Lấy spec OTP ở Ví dụ 3 (POST /api/v1/otp/verify với body { "otp": "string" }). Viết lại spec đó cho hoàn chỉnh: bổ sung mọi ràng buộc, business rule, và error case mà bạn nghĩ nó còn thiếu.
Bài tập 3 — Thực hành công cụ. Mở Swagger Editor (editor.swagger.io) miễn phí, gõ lại spec của Bài tập 1 dưới dạng OpenAPI 3.0 YAML. Sửa cho đến khi editor không còn báo lỗi, rồi quan sát Swagger UI tự render bên phải. Mục tiêu là quen tay với cú pháp OpenAPI.
Bài tập 4 — Định nghĩa conventions. Viết một trang "API Conventions" cho một dự án giả định: quy ước naming, format ngày giờ, cấu trúc error chung, và cách phân trang. Đây là tài liệu mà BA giỏi luôn chuẩn bị trước khi viết endpoint đầu tiên.
Tóm tắt
API documentation là một trong những lĩnh vực mà nền tảng developer biến bạn thành một BA vượt trội — bạn đọc hiểu JSON, status code, và REST một cách tự nhiên. Nhưng giá trị BA thật sự không nằm ở việc biết kỹ thuật, mà ở việc gắn mỗi field, mỗi endpoint với một quyết định nghiệp vụ rõ ràng.
Hãy nhớ ba điều cốt lõi: (1) OpenAPI/Swagger là chuẩn công nghiệp — viết bằng YAML/JSON, máy đọc được, sinh được mock và docs đẹp, dùng tool như Stoplight, Swagger UI, Postman; (2) một spec tốt mô tả đủ cả request, response thành công, response lỗi có ý nghĩa nghiệp vụ, và business rule ẩn — phần error case và ràng buộc field chính là nơi BA tạo khác biệt; (3) độ phức tạp nằm ở ràng buộc chứ không ở số lượng field — một field otp cũng cần spec đầy đủ.
Như các ví dụ từ BeautyBox, dự án Nhật của FSoft Partner, hay sự cố OTP của fintech đã cho thấy: một bản API spec viết cẩu thả gây ra hàng tuần làm sai và khiếu nại khách hàng, còn một bản spec chuẩn mực rút ngắn tích hợp và xây dựng niềm tin giữa các bên. Đây chính là kiểu công việc nơi quá khứ dev của bạn tỏa sáng — hãy tận dụng nó.