Mở đầu — vì sao bài này quan trọng
Nếu bạn từng làm Designer, chắc bạn quen với việc "cái nút này bấm vào sẽ mở màn hình kia". Nhưng khi chuyển sang làm BA, câu hỏi mà dev, QA và cả stakeholder tích hợp sẽ dồn vào bạn là: "Bấm nút đó thì hệ thống gửi cái gì và nhận lại cái gì?". Câu trả lời cho câu hỏi đó nằm trong một thứ gọi là API spec.
Tôi nói thẳng một sự thật mà nhiều bạn Designer chuyển BA hay né tránh: gần như 100% sản phẩm số hiện đại — app ngân hàng, sàn thương mại điện tử, ví điện tử, phần mềm nội bộ — đều là các ứng dụng web/mobile "nói chuyện" với server thông qua API. Nếu requirement của bạn không mô tả được luồng dữ liệu qua API, thì requirement đó không thể kiểm thử được (not testable). Dev sẽ đoán, QA sẽ đoán, và mỗi người đoán một kiểu. Kết quả là bug, là họp đi họp lại, là "sao khác spec của em".
Tin vui là: bạn không cần biết code để đọc và thậm chí viết được API spec. Đây không phải kỹ năng lập trình — nó là kỹ năng đọc hiểu một "hợp đồng" giữa các hệ thống. Và với nền tảng tư duy cấu trúc của Designer (bạn đã quen với component, state, data model của Figma), bạn học nhanh hơn bạn nghĩ. Bài này sẽ cho bạn đủ để đọc một file OpenAPI, hiểu nó nói gì, phát hiện chỗ thiếu, và viết được phần đóng góp của một BA vào tài liệu đó.
Khái niệm cốt lõi
API là gì, hiểu theo kiểu người thật
API (Application Programming Interface) là cách một hệ thống yêu cầu hệ thống khác làm một việc gì đó. Hãy hình dung app Grab: khi bạn bấm "Đặt xe", app trên điện thoại (client) gửi một yêu cầu (request) tới server Grab, đại loại "cho tôi danh sách tài xế gần điểm A". Server xử lý và gửi lại một phản hồi (response) chứa danh sách tài xế. Cuộc trao đổi request–response đó chính là một lần "gọi API".
Mỗi API có một số thành phần cố định mà BA cần nắm:
- Endpoint: địa chỉ của chức năng, ví dụ
/orders(đơn hàng),/users/{id}(người dùng theo ID). - Method (HTTP verb): hành động trên endpoint đó.
GET= lấy dữ liệu,POST= tạo mới,PUT/PATCH= cập nhật,DELETE= xóa. Rất dễ nhớ: đọc, thêm, sửa, xóa. - Request body / parameters: dữ liệu client gửi đi (ví dụ mã sản phẩm, số lượng).
- Response: dữ liệu server trả về, kèm status code —
200(thành công),201(đã tạo),400(client gửi sai),401(chưa đăng nhập),404(không tìm thấy),500(lỗi server).
OpenAPI và Swagger là gì
OpenAPI Specification (OAS) là một chuẩn để mô tả toàn bộ API của một hệ thống dưới dạng văn bản có cấu trúc (thường viết bằng định dạng YAML hoặc JSON). Nó giống như một "bản vẽ kỹ thuật" của API: liệt kê đủ mọi endpoint, method, dữ liệu vào/ra, quy tắc.
Swagger là bộ công cụ phổ biến giúp hiển thị và tương tác với file OpenAPI. Khi ai đó nói "gửi em cái Swagger", họ đang nói đến trang web tự sinh ra từ file OpenAPI (Swagger UI) — nơi bạn thấy danh sách endpoint đẹp đẽ, bấm được, thử được. Ngày nay hai từ này gần như dùng thay nhau, dù về mặt kỹ thuật OpenAPI là chuẩn, còn Swagger là công cụ.
Điều quan trọng với BA: file OpenAPI chính là điểm gặp nhau giữa nghiệp vụ và kỹ thuật. Business rule bạn viết ("số lượng đặt tối đa là 10") phải xuất hiện được ở đâu đó trong spec này (dưới dạng ràng buộc maximum: 10), nếu không nó chỉ là chữ trên Confluence mà dev có thể bỏ sót.
Đọc một mẩu OpenAPI thực tế
Đừng sợ, hãy nhìn ví dụ endpoint tạo đơn hàng viết bằng YAML:
paths:
/orders:
post:
summary: Tạo đơn hàng mới
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [productId, quantity]
properties:
productId:
type: string
quantity:
type: integer
minimum: 1
maximum: 10
responses:
'201':
description: Đơn hàng đã được tạo
'400':
description: Dữ liệu không hợp lệ
Bạn đọc được gì ở đây? Có endpoint /orders, dùng method POST để tạo đơn. Client bắt buộc gửi productId (chuỗi) và quantity (số nguyên, tối thiểu 1, tối đa 10). Nếu thành công trả 201, nếu sai trả 400. Đó — bạn vừa đọc API spec mà không cần biết dòng code nào. required, minimum, maximum chính là business rule được mã hóa vào spec.
Tình huống thực tế
Tình huống 1: Ví điện tử MoMo và cái field bị thiếu
Một BA (vốn xuất thân UX Designer) tại một fintech ở TP.HCM nhận nhiệm vụ viết requirement cho tính năng "chuyển tiền theo số điện thoại". Chị mô tả rất kỹ về UI: màn hình nhập số, màn hình xác nhận, màn hình thành công — đúng chất Designer. Nhưng khi dev đọc, họ hỏi: "Response khi chuyển tiền thành công có trả về transactionId không? Không có ID thì màn hình 'tra cứu giao dịch' lấy gì để tra?".
Chị mới giật mình. Vì chỉ nghĩ theo màn hình, chị bỏ sót một dữ liệu mà nghiệp vụ bắt buộc phải có: mã giao dịch để đối soát. Nếu chị đã đọc quen API spec, chị sẽ tự hỏi ngay từ đầu "response của endpoint POST /transfers gồm những field gì?" và phát hiện thiếu transactionId trước khi dev phải hỏi.
Bài học: Tư duy Designer nghĩ theo màn hình, tư duy BA phải nghĩ thêm theo dữ liệu vào/ra. API spec ép bạn trả lời "hệ thống trả về cái gì" — và câu hỏi đó cứu bạn khỏi hàng loạt lỗ hổng requirement.
Tình huống 2: Tiki tích hợp đối tác giao hàng
Một sàn TMĐT giả định tương tự Tiki cần tích hợp với đối tác vận chuyển (giả sử GHTK) để tự động tạo đơn giao hàng. Bên GHTK gửi cho team một link Swagger UI. BA phụ trách tích hợp mở lên, thấy endpoint POST /shipment/order với các field pick_address, weight (gram), value (giá trị đơn, để tính bảo hiểm).
Nhờ đọc được spec, BA phát hiện hai chuyện quan trọng ngay trong buổi đầu:
weighttính bằng gram, trong khi hệ thống Tiki lưu bằng kg — phải có bước quy đổi, nếu không đơn 2kg sẽ bị khai báo thành 2 gram và tính sai cước.- Endpoint yêu cầu
valuetối đa 20.000.000đ (maximum: 20000000); đơn giá trị cao hơn sẽ bị từ chối400. Đây là business rule của đối tác mà nếu không đọc spec sẽ không ai biết cho tới khi lên production và đơn hàng cao cấp lỗi hàng loạt.
Tình huống 3: Startup EdTech dùng Swagger làm "ngôn ngữ chung"
Một startup EdTech ở Hà Nội có team nhỏ, dev thường "code trước, tài liệu sau". Hậu quả là BA và dev cãi nhau liên miên vì mỗi bên hiểu một kiểu. Một BA mới về đề xuất: mọi tính năng đều phải có một mục OpenAPI trong Confluence, do BA viết nháp phần nghiệp vụ (endpoint cần có, field bắt buộc, business rule dạng min/max/enum), dev bổ sung phần kỹ thuật.
Sau ba tháng, số lần "làm xong mới biết hiểu sai" giảm rõ rệt, vì cả hai bên nhìn chung một hợp đồng. QA cũng dựa vào chính spec đó để viết test case: mỗi status code là một kịch bản kiểm thử.
Bài học: API spec không chỉ để đọc — nó là công cụ giao tiếp và đồng thuận. BA đóng vai trò cầu nối, mang business rule vào spec để requirement trở nên "testable".
Hướng dẫn từng bước
Đây là quy trình để bạn — một BA — làm việc với API spec, kể cả khi bạn chưa từng viết dòng code.
Bước 1 — Xác định endpoint từ user story. Với mỗi hành động người dùng, hỏi "hệ thống cần làm gì với server?". "Xem danh sách khóa học" → GET /courses. "Đăng ký khóa học" → POST /enrollments. Bạn đang dịch hành vi UI thành endpoint.
Bước 2 — Liệt kê dữ liệu vào (request). Người dùng/hệ thống cần gửi gì? Field nào bắt buộc (required), field nào tùy chọn? Ví dụ đăng ký cần courseId (bắt buộc), voucherCode (tùy chọn).
Bước 3 — Liệt kê dữ liệu ra (response) và mã trạng thái. Thành công trả về gì (201 kèm enrollmentId)? Các trường hợp lỗi: 400 khi thiếu field, 409 khi đã đăng ký rồi, 402 khi chưa thanh toán. Mỗi status code là một nhánh nghiệp vụ bạn phải nghĩ tới.
Bước 4 — Gắn business rule vào field. Đây là giá trị lớn nhất BA mang lại. Chuyển quy tắc nghiệp vụ thành ràng buộc: "số lượng 1–10" → minimum: 1, maximum: 10; "trạng thái chỉ gồm ba giá trị" → enum: [pending, paid, cancelled]; "email đúng định dạng" → format: email.
Bước 5 — Đối chiếu và rà soát cùng dev. Đưa spec nháp cho dev. Họ sẽ chỉnh phần kỹ thuật (kiểu dữ liệu, authentication). Bạn kiểm tra ngược lại: mọi business rule của bạn có được phản ánh không?
Bước 6 — Dùng Swagger UI để "thử". Nhiều dự án có Swagger UI cho môi trường test. Bạn có thể bấm "Try it out", nhập dữ liệu và xem response thật. Đây là cách tuyệt vời để BA tự nghiệm thu (một phần) mà không phụ thuộc hoàn toàn vào QA.
Bước 7 — Liên kết ngược về requirement. Ghi chú endpoint tương ứng với từng requirement/user story, phục vụ cho truy vết (traceability) — điều bạn sẽ học sâu hơn ở bài về RTM.
Lỗi thường gặp & mẹo
Lỗi 1: Chỉ mô tả "đường thành công", quên các nhánh lỗi. Designer quen với happy path. Nhưng 40% công sức nghiệp vụ nằm ở xử lý lỗi. Luôn hỏi: field này để trống thì sao? Số âm thì sao? Đăng ký trùng thì sao? Mỗi câu là một status code.
Lỗi 2: Nhầm giữa "field trên UI" và "field trong API". Không phải cứ hiển thị trên màn hình là có trong request. Ngày sinh hiển thị dạng "27/06/2026" nhưng API có thể yêu cầu date chuẩn 2026-06-27. Luôn phân biệt lớp trình bày và lớp dữ liệu.
Lỗi 3: Bỏ qua đơn vị và định dạng. Như tình huống GHTK — gram vs kg, VND vs nghìn đồng, ngày theo múi giờ nào. Đây là nguồn bug kinh điển. Ghi rõ đơn vị vào mô tả field.
Lỗi 4: Viết business rule ở Confluence nhưng không đưa vào spec. Rule chỉ nằm trong văn xuôi rất dễ bị dev bỏ sót. Hãy mã hóa nó thành required, enum, minimum, maximum, format ngay trong schema.
Mẹo hữu ích:
- Dùng editor.swagger.io (miễn phí, trên trình duyệt) để gõ YAML và thấy ngay bản render + báo lỗi cú pháp. Rất hợp để BA tập viết.
- Học thuộc 6 status code hay dùng: 200, 201, 400, 401, 404, 409. Nắm được nhiêu đó là đủ đọc 90% spec.
- Khi nhận spec đối tác, việc đầu tiên là tìm mục authentication (API key? token?) và rate limit (giới hạn số lần gọi) — hai thứ này ảnh hưởng lớn tới nghiệp vụ tích hợp.
- Nghĩ về
enumnhư một dropdown trong Figma: cả hai đều là "danh sách giá trị được phép". Tư duy Designer của bạn ánh xạ trực tiếp sang đây.
Bài tập thực hành
Bài 1 — Đọc hiểu. Cho endpoint sau, hãy trả lời bằng lời: nó làm gì, field nào bắt buộc, business rule là gì, khi nào trả lỗi?
paths:
/reviews:
post:
requestBody:
content:
application/json:
schema:
type: object
required: [courseId, rating]
properties:
courseId: { type: string }
rating: { type: integer, minimum: 1, maximum: 5 }
comment: { type: string, maxLength: 500 }
responses:
'201': { description: Đã tạo đánh giá }
'400': { description: Dữ liệu sai }
'409': { description: Bạn đã đánh giá khóa này rồi }
Bài 2 — Viết spec từ nghiệp vụ. Với user story: "Là học viên, tôi muốn đặt lịch với mentor để được tư vấn", hãy phác một endpoint OpenAPI: đặt tên endpoint và method, liệt kê field request (gợi ý: mentorId, slotTime, topic), đặt ràng buộc phù hợp (topic tối đa 200 ký tự chẳng hạn), và định nghĩa ít nhất ba status code kèm ý nghĩa nghiệp vụ (thành công, mentor bận 409, chưa đăng nhập 401).
Bài 3 — Săn lỗ hổng. Lấy một tính năng bất kỳ trong công ty bạn (hoặc một app bạn dùng hằng ngày). Viết ra 5 câu hỏi về API mà nếu không trả lời được thì requirement chưa "testable". Ví dụ: "Response trả về mã đơn không?", "Đơn vị của trường giá là gì?".
Bài 4 — Thực hành công cụ. Mở editor.swagger.io, dán lời giải Bài 2 của bạn vào, sửa cho hết lỗi cú pháp, và chụp lại màn hình Swagger UI render ra. Đây là artifact bạn có thể đưa vào portfolio BA.
Tóm tắt
API spec (OpenAPI/Swagger) là "hợp đồng" mô tả cách các hệ thống trao đổi dữ liệu, và nó là kỹ năng bắt buộc cho BA hiện đại vì gần như mọi sản phẩm số đều chạy trên API. BA không cần biết code, nhưng cần đọc hiểu được endpoint, method, request/response và status code — và quan trọng nhất là biết mã hóa business rule của mình thành các ràng buộc trong spec (required, enum, minimum, maximum, format) để requirement trở nên kiểm thử được.
Ba điều cần nhớ: (1) Tư duy Designer nghĩ theo màn hình, tư duy BA phải nghĩ thêm theo dữ liệu vào/ra; (2) Với dự án tích hợp, spec của đối tác là nguồn sự thật — hãy soi kỹ đơn vị đo, giới hạn, authentication; (3) API spec là ngôn ngữ chung giúp BA, dev và QA đồng thuận trước khi code. Nắm vững kỹ năng này, bạn không chỉ đọc được spec người khác viết mà còn chủ động dẫn dắt cuộc thảo luận kỹ thuật — đúng vị thế của một BA giỏi.