Làm IT Business Analyst, bạn không nhất thiết phải code API.
Nhưng nếu dự án có tích hợp hệ thống, mobile app, web app, payment, banking, logistics, e-commerce… thì BA rất nên biết cách đọc và viết API Specification ở mức cơ bản.
Vì sao?
Vì API Specification là nơi giúp team thống nhất:
API này dùng để làm gì
Ai gọi API
Input gồm những gì
Output trả về gì
Khi lỗi thì trả lỗi gì
Field nào bắt buộc
Status nào được xem là thành công, thất bại, pending
Nếu API Spec viết mơ hồ, Dev sẽ hiểu một kiểu, QA test một kiểu, frontend xử lý lỗi một kiểu, và BA là người bị hỏi lại nhiều nhất.
API Specification được mô tả là một chuẩn độc lập ngôn ngữ lập trình để mô tả HTTP API, giúp cả con người và máy tính hiểu khả năng của service mà không cần đọc source code hay inspect network traffic. (OpenAPI Initiative Publications)
1. API Specification là gì?
API Specification là tài liệu mô tả chi tiết cách một API hoạt động.
Nó giống như một “hợp đồng” giữa các bên:
Frontend
Backend
Mobile app
Hệ thống bên thứ ba
QA
BA
Đối tác tích hợp
Một API Spec tốt phải trả lời được:
API này phục vụ nghiệp vụ gì?
Khi nào API được gọi?
Request cần dữ liệu gì?
Response trả dữ liệu gì?
Lỗi xảy ra thì trả về thế nào?
Có cần authentication không?
Có timeout, retry, idempotency không?
2. BA viết API Spec đến mức nào là đủ?
Newbie BA không cần viết API Spec sâu như Solution Architect hoặc Backend Developer.
Nhưng BA nên viết được phần nghiệp vụ của API:
Mục đích API
Luồng gọi API
Input, output ở mức business field
Business rule
Error case
Message hiển thị cho user
Status mapping
NFR liên quan
Phần quá kỹ thuật như database indexing, framework, internal implementation thì để dev/tech lead xử lý.
Nói đơn giản:
BA không cần quyết định API code thế nào.
Nhưng BA phải mô tả rõ API cần phục vụ nghiệp vụ nào và dữ liệu nào phải đúng.
3. Cấu trúc cơ bản của một tài liệu API Specification
Một API Spec cơ bản nên có các phần sau:
1. API Overview
2. Business Context
3. Endpoint
4. HTTP Method
5. Authentication
6. Request Parameters
7. Request Body
8. Response Body
9. Status Code
10. Error Code
11. Business Rules
12. Validation Rules
13. Example Request/Response
14. Timeout/Retry/Idempotency
15. Audit Log
16. Notes / Assumptions
MDN giải thích HTTP method thể hiện mục đích của request, còn HTTP status code cho biết request đã được hoàn tất thành công hay chưa. Vì vậy trong API Spec, method và status code là hai phần BA nên hiểu tối thiểu.
4. Ví dụ case: API chuyển khoản nội bộ
Giả sử BA cần đặc tả API cho tính năng chuyển khoản nội bộ trong mobile banking.
User flow:
User nhập tài khoản nhận
User nhập số tiền
User xác nhận OTP
Hệ thống tạo giao dịch
Trừ tiền người gửi
Cộng tiền người nhận
Hiển thị biên lai
API chính có thể là:
POST /internal-transfers
5. API Overview
Phần này mô tả API dùng để làm gì.
Ví dụ:
API Name: Create Internal Transfer
Purpose: Create a money transfer transaction between two accounts within the same bank.
Actor/System: Mobile Banking App calls Banking Backend.
Trigger: Customer confirms transfer after entering OTP.
Viết đơn giản nhưng phải rõ nghiệp vụ.
Không nên viết chung chung kiểu:
API dùng để xử lý giao dịch.
Nên viết cụ thể:
API dùng để tạo giao dịch chuyển khoản nội bộ sau khi khách hàng xác nhận OTP thành công.
6. Business Context
Phần này giải thích vì sao API tồn tại trong flow.
Ví dụ:
This API is called after the customer enters receiver account, transfer amount, description, and successfully confirms OTP. The API validates account status, available balance, daily transfer limit, duplicate request, then creates an internal transfer transaction.
BA nên viết phần này để dev/QA hiểu API nằm ở bước nào trong nghiệp vụ.
7. Endpoint và Method
Ví dụ:
Endpoint: /internal-transfers
Method: POST
Vì sao dùng POST?
Vì API này tạo một giao dịch mới.
Một số method phổ biến:
GET Lấy dữ liệu
POST Tạo mới
PUT Cập nhật toàn bộ
PATCH Cập nhật một phần
DELETE Xóa
Ví dụ:
GET /accounts/{accountId}/balance
POST /internal-transfers
PATCH /cards/{cardId}/status
DELETE /beneficiaries/{beneficiaryId}
8. Authentication và Authorization
Phần này trả lời:
User có cần đăng nhập không?
Token có bắt buộc không?
User có quyền gọi API này không?
Ví dụ:
Authentication: Required
Authorization: Customer can transfer only from accounts owned by them.
Token: Bearer access token
Newbie rất hay nhầm:
Authentication là xác thực bạn là ai.
Authorization là bạn được phép làm gì.
Ví dụ:
User đăng nhập thành công nhưng không được chuyển tiền từ tài khoản của người khác.
9. Request Header
Header chứa thông tin bổ sung cho request.
Ví dụ:
Authorization: Bearer {access_token}
Content-Type: application/json
Idempotency-Key: {unique_request_id}
X-Request-Id: {trace_id}
BA không cần biết toàn bộ header kỹ thuật, nhưng với Banking/Payment nên chú ý:
Authorization
Content-Type
Request ID
Idempotency Key
Correlation ID hoặc Trace ID
Vì các field này giúp chống duplicate request và điều tra lỗi.
10. Request Parameters
Parameter là dữ liệu truyền kèm qua đường dẫn hoặc query.
Ví dụ path parameter:
GET /accounts/{accountId}/balance
Trong đó accountId là path parameter.
Ví dụ query parameter:
GET /transactions?fromDate=2026-01-01&toDate=2026-01-31&page=1&pageSize=20
Query parameter thường dùng cho:
Filter
Search
Sorting
Pagination
Với API tạo giao dịch bằng POST, nhiều thông tin sẽ nằm trong request body.
11. Request Body
Request body mô tả dữ liệu gửi lên server.
Ví dụ:
{
"sourceAccountId": "ACC001",
"receiverAccountNo": "1234567890",
"amount": 1000000,
"currency": "VND",
"description": "Transfer money",
"otpToken": "123456"
}
12. Validation Rules
Đây là phần rất quan trọng với BA.
Ví dụ:
VR-01: sourceAccountId is required.
VR-02: receiverAccountNo is required and must be numeric.
VR-03: amount must be greater than or equal to 10,000 VND.
VR-04: currency must be VND.
VR-05: description maximum length is 140 characters.
VR-06: otpToken is required and must be 6 digits.
Validation rule trả lời:
Field nào bắt buộc?
Format như thế nào?
Min/max bao nhiêu?
Có giới hạn ký tự không?
Có cho phép null không?
Có trim khoảng trắng không?
13. Business Rules
Validation Rule khác Business Rule.
Validation Rule kiểm tra dữ liệu đúng format.
Business Rule kiểm tra nghiệp vụ có hợp lệ không.
Ví dụ Business Rule cho chuyển khoản:
BR-01: Source account must be active.
BR-02: Receiver account must exist and be active.
BR-03: Transfer amount must not exceed available balance.
BR-04: Transfer amount must not exceed daily transfer limit.
BR-05: Daily transfer limit depends on customer KYC level.
BR-06: OTP must be valid and not expired.
BR-07: Duplicate request with same Idempotency-Key must not create a new transaction.
Ví dụ dễ hiểu:
Amount là số dương → validation rule.
Amount không vượt hạn mức KYC → business rule.
14. Success Response
Response thành công nên mô tả rõ API trả gì.
Ví dụ:
{
"transactionId": "TXN202608020001",
"status": "SUCCESS",
"sourceAccountId": "ACC001",
"receiverAccountNo": "1234567890",
"receiverName": "NGUYEN VAN A",
"amount": 1000000,
"fee": 0,
"currency": "VND",
"createdAt": "2026-08-02T09:30:00+07:00",
"message": "Transfer successful"
}
15. Status Code
Ví dụ status code:
201 Created: Transfer transaction created successfully.
400 Bad Request: Invalid request format.
401 Unauthorized: Token is missing or invalid.
403 Forbidden: Customer is not allowed to transfer from this account.
404 Not Found: Receiver account not found.
409 Conflict: Duplicate transaction request.
422 Unprocessable Entity: Business validation failed.
500 Internal Server Error: Unexpected system error.
503 Service Unavailable: Core banking service unavailable.
BA không cần thuộc tất cả status code, nhưng nên hiểu nhóm:
2xx là thành công
4xx là lỗi từ request hoặc quyền truy cập
5xx là lỗi hệ thống/server
16. Error Response
Một API Spec tốt không chỉ có success response.
Nó phải có error response rõ ràng.
Ví dụ:
{
"errorCode": "INSUFFICIENT_BALANCE",
"message": "Your available balance is not enough.",
"details": {
"availableBalance": 500000,
"requiredAmount": 1000000
}
}
Error code rất quan trọng vì giúp:
Frontend hiển thị đúng message
QA viết test case
CSKH tra cứu nguyên nhân
Dev debug nhanh hơn
17. Transaction Status Mapping
Với những API liên quan Banking, Payment, E-commerce Order, Logistics, BA nên định nghĩa status rõ ràng.
Nếu không định nghĩa status rõ, UI có thể hiển thị sai, QA test thiếu, CSKH không biết giải thích thế nào.
18. Timeout, Retry, Idempotency
Với các API quan trọng, đặc biệt là payment/transfer, phần này không được bỏ qua.
Ví dụ:
Timeout: 30 seconds
Retry: No automatic retry for money transfer creation unless idempotency key is used
Idempotency: Required
Duplicate handling: If same Idempotency-Key is received, return original transaction result
BA cần hỏi:
Timeout sau bao lâu?
Timeout thì status là gì?
Có retry không?
Retry có gây giao dịch trùng không?
Có idempotency key không?
Request trùng thì trả response cũ hay báo lỗi?
19. Audit Log
Với API nhạy cảm, audit log là bắt buộc.
Ví dụ audit log cho chuyển khoản:
Customer ID
Source account
Receiver account masked
Amount
Transaction ID
Device ID
IP Address
OTP result
Timestamp
Status change
Error code if failed
BA nên yêu cầu:
Không log dữ liệu nhạy cảm dạng thô
Có trace ID để điều tra lỗi
Ghi lại status change
Ai gọi API, khi nào, kết quả gì
20. Example Request và Response
API Spec nên có ví dụ cụ thể.
Ví dụ request:
POST /internal-transfers
Authorization: Bearer access_token
Content-Type: application/json
Idempotency-Key: 9f6b0f1e-1234-4567
{
"sourceAccountId": "ACC001",
"receiverAccountNo": "1234567890",
"amount": 1000000,
"currency": "VND",
"description": "Transfer money",
"otpToken": "123456"
}
Ví dụ response thành công:
{
"transactionId": "TXN202608020001",
"status": "SUCCESS",
"message": "Transfer successful"
}
Ví dụ response lỗi:
{
"errorCode": "LIMIT_EXCEEDED",
"message": "Transfer amount exceeds daily limit."
}
Có ví dụ cụ thể sẽ giúp Dev, QA và stakeholder hiểu nhanh hơn rất nhiều.
21. Template API Specification cho BA
Bạn có thể dùng mẫu sau:
API Name:
Purpose:
Business Context:
Actor/System:
Trigger:
Endpoint:
Method:
Authentication:
Authorization:
Request Headers:
Path Parameters:
Query Parameters:
Request Body:
Validation Rules:
Business Rules:
Success Response:
Error Response:
HTTP Status Codes:
Error Codes:
Status Mapping:
Timeout:
Retry:
Idempotency:
Audit Log:
Assumptions:
Open Questions:
22. Checklist tự review API Spec trước khi gửi team
[ ] API này phục vụ nghiệp vụ gì đã rõ chưa?
[ ] Ai gọi API này đã rõ chưa?
[ ] API được gọi ở bước nào trong flow?
[ ] Endpoint và method đã rõ chưa?
[ ] Authentication/authorization đã rõ chưa?
[ ] Request body có đủ field chưa?
[ ] Field nào required đã ghi rõ chưa?
[ ] Validation rule đã rõ chưa?
[ ] Business rule đã tách riêng chưa?
[ ] Success response có ví dụ chưa?
[ ] Error response có ví dụ chưa?
[ ] Error code có đủ để UI xử lý chưa?
[ ] Status mapping đã rõ chưa?
[ ] Timeout/retry đã được định nghĩa chưa?
[ ] Có cần idempotency không?
[ ] Có audit log không?
[ ] Có open questions cần confirm không?
23. 5 lỗi newbie hay mắc khi viết API Spec
1. Chỉ viết request, không viết error response
Kết quả là khi lỗi xảy ra, frontend không biết hiển thị gì.
2. Không tách validation rule và business rule
Dẫn đến dev khó biết lỗi nào do format, lỗi nào do nghiệp vụ.
3. Không định nghĩa trạng thái
Đặc biệt nguy hiểm với payment, transfer, order, delivery.
4. Không nghĩ đến timeout và retry
Dễ gây lỗi duplicate hoặc trạng thái treo.
5. Không có ví dụ request/response
Tài liệu trở nên khó hiểu và khó review.
Kết luận
API Specification không chỉ là tài liệu kỹ thuật.
Với BA, API Spec là cách biến requirement thành một hợp đồng rõ ràng giữa các hệ thống.
Một API Spec tốt giúp:
Dev code đúng
QA test đủ
Frontend xử lý lỗi đúng
Stakeholder hiểu trạng thái nghiệp vụ
CSKH giải thích được lỗi cho user
Newbie BA không cần viết API Spec quá phức tạp ngay từ đầu.
Nhưng hãy nắm chắc:
Request
Response
Status code
Error code
Business rule
Validation rule
Timeout
Retry
Idempotency
Audit log
Chỉ cần những phần này, bạn đã khác rất nhiều Fresher chỉ biết mô tả UI.
