Mở đầu — vì sao bài này quan trọng
Nếu bạn đến từ nền QA và đã từng mở Postman để bắn một request GET /api/orders/123, từng kiểm tra status code 200 so với 404, từng so sánh response JSON với expected result trong test case của mình — thì xin chúc mừng: bạn đã làm một nửa công việc viết API spec mà nhiều BA "thuần business" phải vật lộn mới hiểu nổi.
Đây chính là một trong những lợi thế cạnh tranh lớn nhất, nhưng lại ít được nói tới nhất, của người QA chuyển sang BA. Trong thị trường BA Việt Nam 2026, đặc biệt ở các công ty làm sản phẩm số (fintech, e-commerce, SaaS) và outsource cho client nước ngoài, ngày càng nhiều dự án yêu cầu BA phải viết hoặc review API specification — tài liệu mô tả cách các hệ thống "nói chuyện" với nhau qua API. BA nào làm được việc này sẽ ngồi đúng vào chỗ giao thoa giữa business và kỹ thuật, nơi mà lương và quyền lực ra quyết định đều cao hơn.
Tin vui là: bạn không phải học từ con số 0. Bạn đã có sẵn "tư duy contract" — tư duy về việc một API phải nhận gì, trả gì, và xử lý lỗi ra sao — từ những ngày test API. Bài này sẽ giúp bạn chuyển hóa kỹ năng test API thành kỹ năng đặc tả (specify) API: từ người kiểm chứng cái contract đã có, thành người viết ra chính cái contract đó. Chúng ta sẽ tập trung vào OpenAPI/Swagger — chuẩn công nghiệp cho REST API — và cách một BA viết, đọc, review tài liệu này.
Khái niệm cốt lõi
API spec là gì, và tại sao nó là "contract"
API specification là bản hợp đồng kỹ thuật giữa bên cung cấp API (backend team) và bên tiêu thụ API (frontend, mobile, hệ thống đối tác). Nó định nghĩa chính xác:
- Endpoint — đường dẫn và phương thức, ví dụ
POST /api/v1/orders. - Request — dữ liệu gửi lên: path params, query params, headers, và body (thường là JSON).
- Response — dữ liệu trả về cho từng mã trạng thái:
200,201,400,401,404,409,500... - Data schema — cấu trúc và kiểu dữ liệu của từng trường:
string,integer,boolean,enum, bắt buộc hay tùy chọn, ràng buộc độ dài/định dạng. - Error handling — khi nào trả lỗi gì, message ra sao.
OpenAPI / Swagger — chuẩn để mô tả REST API
OpenAPI Specification (OAS) là chuẩn mở, phổ biến nhất hiện nay để mô tả REST API. Swagger là bộ công cụ đi kèm (Swagger UI, Swagger Editor) giúp render file OpenAPI thành tài liệu tương tác đẹp mắt mà cả dev lẫn business đều xem được. Người ta hay dùng lẫn lộn hai từ này, nhưng nhớ: OpenAPI là chuẩn, Swagger là công cụ.
File OpenAPI thường viết bằng YAML (hoặc JSON). YAML dễ đọc với con người, dùng thụt lề để thể hiện cấu trúc lồng nhau — rất giống cách bạn nhìn một JSON response trong Postman, chỉ bỏ bớt dấu ngoặc. Một mẩu OpenAPI mô tả endpoint tạo đơn hàng trông như thế này:
paths:
/api/v1/orders:
post:
summary: Tạo đơn hàng mới
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [customerId, items]
properties:
customerId:
type: string
example: "CUST-00123"
items:
type: array
items:
type: object
required: [sku, quantity]
properties:
sku: { type: string }
quantity: { type: integer, minimum: 1 }
responses:
'201':
description: Tạo đơn thành công
'400':
description: Dữ liệu không hợp lệ
'409':
description: Sản phẩm hết hàng
Một BA không cần phải code, nhưng cần đọc được khối này và biết nó nói gì về nghiệp vụ: đơn hàng phải có khách hàng và ít nhất một sản phẩm; mỗi item phải có mã SKU và số lượng tối thiểu là 1; nếu hết hàng thì hệ thống trả 409. Mỗi dòng kỹ thuật đều mang một business rule.
Vai trò của BA so với QA và Dev trong API spec
Ranh giới hay gây lúng túng, nên làm rõ ngay:
- BA sở hữu phần "API phải làm gì để phục vụ nghiệp vụ" — cần endpoint nào, trường nào, ràng buộc nghiệp vụ nào, mã lỗi nghiệp vụ nào. BA viết hoặc đồng tác giả phần mô tả này.
- Dev/Tech Lead/Solution Architect sở hữu phần "API được thiết kế kỹ thuật ra sao" — cấu trúc URL, versioning, authentication, hiệu năng, kiểu dữ liệu chi tiết.
- QA kiểm chứng API chạy đúng như spec.
quantity = 0 thì trả lỗi gì? Message tiếng Việt hay tiếng Anh? Có cho phép số âm không?" — những câu hỏi mà chính bạn từng phải tự bịa ra khi viết test case vì spec gốc bỏ trống.Tình huống thực tế
Tình huống 1 — Tiki: BA viết API spec cho tính năng "đặt trước" (pre-order)
Một công ty e-commerce lớn tại TP.HCM (tạm gọi theo mô hình Tiki) muốn thêm tính năng đặt trước sản phẩm chưa mở bán. Lan, một BA vừa chuyển từ vị trí QA Engineer sau 4 năm test API cho team thanh toán, được giao viết spec cho endpoint POST /api/v1/preorders.
Nhờ phản xạ QA cũ, Lan không viết spec theo kiểu "tạo một pre-order với thông tin khách hàng". Cô lập tức nghĩ theo các case mà mình từng phải test: khách đặt trước một sản phẩm đã hết hạn pre-order thì sao? Đặt số lượng vượt giới hạn (giả sử mỗi người tối đa 2 cái) thì sao? Đặt trước nhưng chưa có địa chỉ giao hàng? Cô đưa hết vào spec dưới dạng các response code rõ ràng: 201 thành công, 400 thiếu dữ liệu, 403 chưa đủ điều kiện (tài khoản chưa xác thực), 409 đã quá hạn pre-order, 422 vượt giới hạn số lượng.
Kết quả: bản spec của Lan có 6 nhánh response trong khi bản nháp ban đầu của team chỉ có 2 (200 và 500). Trong buổi review, Tech Lead thừa nhận đã quên mất case "vượt giới hạn số lượng" — vốn là một business rule chống đầu cơ hàng hot. Bug đó nếu lọt ra production có thể cho phép một người gom 50 chiếc iPhone pre-order.
Bài học: Tư duy edge-case của QA biến BA thành người viết spec đầy đủ nhánh lỗi — thứ mà BA thuần business thường bỏ sót. Spec tốt không phải spec mô tả đẹp đường happy path, mà là spec liệt kê đủ các nhánh hỏng.
Tình huống 2 — Công ty outsource cho client Singapore: review API spec do đối tác cung cấp
Minh làm BA tại một công ty outsource ở Hà Nội, dự án tích hợp hệ thống loyalty của một chuỗi F&B Singapore. Client gửi sang một file Swagger gồm 40 endpoint, yêu cầu team Việt Nam tích hợp. Minh, vốn xuất thân QA, được giao đọc và "estimate độ phức tạp".
Thay vì đọc lướt, Minh mở file YAML trong Swagger Editor và làm đúng điều anh từng làm khi test: dò từng endpoint xem cái gì còn mơ hồ. Anh phát hiện endpoint GET /members/{id}/points không ghi rõ đơn vị điểm là số nguyên hay có phần thập phân, không nói điểm có thể âm không (trường hợp hoàn/hủy giao dịch), và expiryDate không ghi timezone — một cái bẫy kinh điển vì Singapore là UTC+8 còn server có thể chạy UTC.
Minh tổng hợp 14 câu hỏi gửi lại client trước khi code một dòng nào. Client phản hồi rằng 3 trong số đó họ "chưa từng nghĩ tới". Nhờ vậy, dự án tránh được một vòng rework lớn về xử lý timezone — thứ mà nếu phát hiện ở giai đoạn UAT sẽ tốn cả tuần và làm xấu mặt công ty với client.
Bài học: BA từ nền QA đọc API spec không phải để "hiểu cho biết" mà để truy vấn sự mơ hồ. Mỗi trường thiếu ràng buộc là một câu hỏi tiềm năng cho stakeholder. Đây là kỹ năng elicitation (khai thác yêu cầu) ngụy trang dưới lớp áo kỹ thuật.
Tình huống 3 — Fintech VN: BA dùng Postman collection làm bản nháp cho spec
Tại một startup ví điện tử ở Việt Nam, Hùng (cựu QA Automation) cần spec hóa API rút tiền POST /withdrawals cho team tài liệu hóa lại hệ thống legacy vốn không có tài liệu. Hệ thống đã chạy nhưng spec thì thất lạc — một tình huống cực phổ biến ở các công ty Việt.
Hùng tận dụng đúng tài sản QA của mình: bộ Postman collection cũ anh từng dùng test luồng rút tiền. Mỗi request đã có sẵn ví dụ body, mỗi test script đã ghi rõ expected status. Anh dùng tính năng export và công cụ chuyển đổi để dựng khung OpenAPI từ collection đó, rồi ngồi bổ sung phần nghiệp vụ: hạn mức rút tối thiểu 50.000đ, tối đa 20.000.000đ/ngày, lỗi 409 khi số dư không đủ, lỗi 429 khi vượt số lần rút trong ngày.
Trong 2 ngày, Hùng dựng được spec cho 8 endpoint — việc mà một BA không có background kỹ thuật ước tính phải mất 2 tuần phỏng vấn dev.
Bài học: Postman collection của bạn (ví dụ request/response thật) là nguyên liệu thô tuyệt vời để dựng API spec. Đừng vứt nó đi khi chuyển nghề — nó là kho vàng tài liệu.
Hướng dẫn từng bước
Đây là quy trình thực dụng để một BA từ nền QA viết một API spec từ một yêu cầu nghiệp vụ:
Bước 1 — Bắt đầu từ business goal, không phải từ endpoint. Trả lời: tính năng này phục vụ ai làm gì? Ví dụ "cho phép khách hàng hủy đơn trong vòng 30 phút sau khi đặt". Đừng nhảy ngay vào URL.
Bước 2 — Xác định các endpoint cần thiết. Từ business goal, suy ra hành động: hủy đơn → POST /api/v1/orders/{orderId}/cancel. Đặt tên theo danh từ tài nguyên (orders) và động từ HTTP (POST/GET/PUT/DELETE). Một mẹo cho người QA: nghĩ về những "luồng" bạn sẽ phải test — mỗi luồng thường tương ứng một endpoint.
Bước 3 — Định nghĩa request. Liệt kê dữ liệu đầu vào: path param (orderId), body (lý do hủy?), header (token xác thực). Với mỗi trường, ghi rõ: kiểu dữ liệu, bắt buộc hay không, ràng buộc (độ dài, enum giá trị hợp lệ). Đây chính là phần bạn từng tạo "test data" — giờ bạn định nghĩa nó.
Bước 4 — Liệt kê đầy đủ response, đặc biệt các nhánh lỗi. Đây là lúc tư duy QA tỏa sáng. Đừng dừng ở 200. Hỏi: đơn không tồn tại (404)? Đơn đã quá 30 phút (409 hoặc 422)? Đơn đã giao rồi (409)? Người dùng không sở hữu đơn này (403)? Token hết hạn (401)? Mỗi nhánh ghi rõ business message.
Bước 5 — Gắn business rule vào từng ràng buộc. Với mỗi con số và mỗi mã lỗi, ghi chú vì sao. "30 phút" đến từ đâu? Chính sách hoàn tiền nào? Điều này biến spec kỹ thuật thành tài liệu nghiệp vụ truy vết được.
Bước 6 — Viết ra OpenAPI/YAML hoặc dùng công cụ. Bạn có thể viết tay YAML trong Swagger Editor (xem preview ngay), hoặc dùng công cụ no-code như Stoplight Studio để điền form. Không cần thuộc lòng cú pháp — cần hiểu cấu trúc.
Bước 7 — Review chéo với Dev và QA. Đưa spec cho Tech Lead xác nhận tính khả thi kỹ thuật, đưa cho QA để họ thử "phá" bằng các case bạn có thể quên. Bạn từng ở phía QA, hãy mời chính họ làm điều bạn từng làm.
Lỗi thường gặp & mẹo
Lỗi 1 — Sa đà vào thiết kế kỹ thuật không thuộc phần mình. BA mới từ QA hay sa vào tranh luận kiểu nên dùng PUT hay PATCH, đặt URL số ít hay số nhiều. Đó là việc của architect. Phần của bạn là nghiệp vụ: trường nào cần, ràng buộc gì, lỗi gì. Đừng để cái nền kỹ thuật kéo bạn ra khỏi vai trò BA.
Lỗi 2 — Chỉ mô tả happy path. Trớ trêu là QA chuyển BA đôi khi vẫn mắc lỗi này vì sức ép deadline. Nhớ: giá trị lớn nhất bạn mang lại chính là các nhánh lỗi. Một spec không có mục error response là spec chưa xong một nửa.
Lỗi 3 — Bỏ trống ràng buộc dữ liệu. Viết amount: number mà không nói min/max, âm/dương, đơn vị (VND hay xu?), số chữ số thập phân. Mỗi chỗ trống là một bug tương lai. Dùng phản xạ "test data invalid" của QA để bịt các lỗ này.
Lỗi 4 — Nhầm message kỹ thuật với message nghiệp vụ. 500 Internal Server Error là chuyện của dev; còn "Số dư không đủ để rút" là chuyện của bạn. Đảm bảo các lỗi nghiệp vụ có message rõ ràng, đúng ngôn ngữ người dùng (tiếng Việt cho user VN).
Mẹo vàng: Giữ lại và tái sử dụng các Postman collection cũ. Chúng chứa ví dụ request/response thật — nguyên liệu quý để viết phần example trong spec, giúp dev và đối tác hiểu nhanh.
Mẹo về versioning: Luôn để ý prefix version (/v1/). Khi spec thay đổi phá vỡ tương thích (breaking change), đó là tín hiệu cần version mới — và là lúc bạn phối hợp với QA về regression.
Bài tập thực hành
- Đọc và truy vấn. Lên
petstore.swagger.io(Swagger demo công khai), chọn một endpoint bất kỳ. Viết ra 5 câu hỏi nghiệp vụ mà spec đó không trả lời (ví dụ: trường này có bắt buộc không, lỗi gì khi trùng dữ liệu).
- Chuyển test case thành spec. Lấy một test case API bạn từng viết thời QA. Viết lại nó thành một mục response trong OpenAPI: status code, mô tả, ví dụ body. Cảm nhận việc "đảo chiều" từ kiểm chứng sang đặc tả.
- Viết spec mini. Cho yêu cầu: "Khách hàng đăng ký nhận voucher sinh nhật, mỗi email chỉ được đăng ký 1 lần, voucher chỉ áp dụng cho khách có đơn hàng trong 6 tháng gần nhất." Hãy viết khung OpenAPI cho endpoint
POST /api/v1/birthday-vouchers: liệt kê request body, ít nhất 4 response code kèm business message, và gắn business rule vào từng ràng buộc.
- Review chéo. Đưa spec mini ở bài 3 cho một đồng nghiệp (hoặc tự đóng vai QA) và yêu cầu họ tìm 3 case bạn bỏ sót. Ghi lại để rút kinh nghiệm.
Tóm tắt
API spec là bản hợp đồng định nghĩa cách các hệ thống trao đổi dữ liệu — và viết được nó là một lợi thế nghề nghiệp lớn cho BA tại Việt Nam 2026. Người QA chuyển BA bước vào sân chơi này với hành trang sẵn có: tư duy contract (request/response/error), phản xạ edge-case, và kho Postman collection từ thời test. OpenAPI/Swagger là chuẩn để mô tả REST API, thường viết bằng YAML dễ đọc; BA không cần code nhưng cần đọc, viết và review được nó ở góc độ nghiệp vụ.
Điều cốt lõi cần nhớ: vai trò BA của bạn không phải thiết kế kiến trúc API mà là đảm bảo API phục vụ đúng nghiệp vụ — đầy đủ trường, đầy đủ ràng buộc, và đặc biệt là đầy đủ nhánh lỗi. Hãy lấy chính điểm mạnh QA — săn case lỗi và truy vấn sự mơ hồ — làm vũ khí, biến nó thành những bản spec mà cả dev, QA lẫn stakeholder đều tin tưởng.