Tài liệu thiết kế API: cấu trúc để đội khác tích hợp được
Một tài liệu API tốt trả lời được câu hỏi của người sẽ tích hợp mà không cần gặp tác giả. Bài này đưa ra cấu trúc mười hai phần, chỉ ra phần hay bị bỏ nhất và cách viết lại một dòng đặc tả kém.
Mục lục bài viết
Trả lời nhanh
Tài liệu thiết kế API cần mười hai phần, định danh tài nguyên đến chính sách phiên bản. Kèm bảng viết lại dòng đặc tả kém và chi phí ba năm khi thiếu tài liệu.
Tài liệu thiết kế API mô tả hợp đồng giữa hai hệ thống đủ chi tiết để đội khác viết mã gọi mà không phải hỏi tác giả. Tài liệu tốt chốt tài nguyên, trường dữ liệu, mã lỗi và chính sách phiên bản; tài liệu mơ hồ biến mỗi lần tích hợp thành một dự án nhỏ.
Tóm tắt nhanh
- Tài liệu API mô tả cam kết, không mô tả mã nguồn.
- Cần mười hai phần; thiếu phần nào cũng dẫn đến một loại hiểu sai.
- Ba phần hay bị bỏ nhất là lỗi, ví dụ và chính sách phiên bản.
- Một dòng đặc tả kém thường thiếu đơn vị, giá trị rỗng hoặc điều kiện.
- Chi phí của tài liệu thiếu thể hiện ở số câu hỏi lặp lại và chi phí thay đổi.
Tài liệu API khác tài liệu hướng dẫn ở đâu
Tài liệu hướng dẫn sử dụng trả lời "làm sao để gọi". Tài liệu thiết kế trả lời "hợp đồng là gì và cái gì được phép thay đổi". Gộp hai loại làm một thì tài liệu chỉ có ví dụ đúng, không có cam kết.
Ba câu hỏi chỉ tài liệu thiết kế trả lời được:
Trường nào bắt buộc, trường nào có thể vắng? Ví dụ luôn có đủ trường, nên không cho biết trường nào tuỳ chọn.
Khi nào phải thử lại? Ví dụ đúng không cho biết lỗi tạm thời trông thế nào; bên gọi sẽ thử lại cả lỗi vĩnh viễn và tạo dữ liệu trùng.
Thay đổi nào sẽ phá tôi? Đây là câu hỏi về chính sách phiên bản. Không có phần này, mỗi lần phát hành là một rủi ro chưa lượng hoá.
Viết tài liệu thiết kế như trang giới thiệu tính năng là sai lầm: dễ đọc nhưng không dùng được để lập trình.
Mười hai phần của một tài liệu thiết kế API
| Phần | Nội dung | Điều gì xảy ra nếu thiếu |
|---|---|---|
| Mục tiêu và phạm vi | API phục vụ tình huống nào, không phục vụ gì | Bên gọi dùng sai mục đích, yêu cầu tính năng ngoài phạm vi |
| Bên gọi và tần suất | Ai gọi, gọi bao nhiêu, từ đâu | Không đánh giá được tải và giới hạn |
| Xác thực | Cách lấy quyền, thời hạn, cách gia hạn | Mỗi bên tự đoán, sai lệch khi hết hạn |
| Phân quyền | Ai được đọc, ghi, xoá tài nguyên nào | Lộ dữ liệu hoặc chặn nhầm người dùng hợp lệ |
| Danh mục tài nguyên | Danh từ, định danh, quan hệ cha con | Đường dẫn mọc tự phát, khó mở rộng |
| Trường dữ liệu | Kiểu, đơn vị, múi giờ, giá trị rỗng | Tính sai tiền, sai thời gian, sai số lượng |
| Ví dụ yêu cầu và phản hồi | Một ví dụ đầy đủ cho mỗi tình huống chính | Bên gọi thử sai nhiều lần mới ra kết quả |
| Mã lỗi | Mã ổn định, ý nghĩa, có thử lại được không | Thử lại lỗi vĩnh viễn, gửi trùng dữ liệu |
| Phân trang và lọc | Kiểu phân trang, giới hạn, thứ tự sắp xếp | Bỏ sót hoặc lặp bản ghi trong báo cáo |
| Giới hạn tần suất | Ngưỡng, cách báo khi vượt, cách chờ | Bị chặn đột ngột, không biết khi nào thử lại |
| Chính sách phiên bản | Cách đánh phiên bản, thời gian hỗ trợ | Không ai dám đổi, hoặc đổi làm sập bên gọi |
| Nhật ký thay đổi | Ngày, thay đổi, ảnh hưởng tương thích | Bên gọi phát hiện thay đổi qua sự cố |
Mười hai phần này không dài: với API nội bộ nhỏ, mỗi phần chỉ vài dòng. Điều quan trọng là không phần nào vắng, vì mỗi phần tương ứng một loại hiểu sai.
Ba phần hay bị bỏ nhất
Mã lỗi. Đây là phần bị bỏ nhiều nhất vì người viết thường cho rằng lỗi là ngoại lệ. Nhưng với bên gọi, lỗi là luồng chính: mạng chập chờn, dữ liệu trùng, quyền hết hạn. Thiếu danh mục mã lỗi, bên gọi phải đoán qua thông điệp.
Ví dụ đầy đủ. Ví dụ rút gọn chỉ vài trường không cho biết trường nào luôn có mặt. Nên có một ví dụ đầy đủ cho mỗi tình huống chính, kể cả tình huống lỗi.
Chính sách phiên bản. Phần này hay bị hoãn vì "chưa cần". Đến khi cần thì đã có bên gọi phụ thuộc, và mọi quyết định đều phải thương lượng dưới áp lực. Viết chính sách khi API còn ít bên gọi rẻ hơn nhiều.
Ba phần này đều mô tả trường hợp xấu. Tài liệu dễ bị viết chỉ cho trường hợp tốt, vì đó là thứ người viết đang nghĩ tới.
Viết lại một dòng đặc tả kém
| Dòng kém | Vấn đề | Dòng viết lại |
|---|---|---|
amount: số tiền |
Không rõ đơn vị, không rõ kiểu | amount: số nguyên, đơn vị đồng, không âm, bắt buộc |
created_at: thời gian tạo |
Không rõ múi giờ, không rõ định dạng | created_at: chuỗi theo chuẩn quốc tế, luôn có múi giờ, chỉ đọc |
status: trạng thái đơn |
Không có tập giá trị, không có quy tắc mở rộng | status: một trong cho_xac_nhan, dang_giao, hoan_tat, da_huy; giá trị lạ phải xử lý như cho_xac_nhan |
items: danh sách sản phẩm |
Không rõ số lượng tối đa, không rõ bắt buộc | items: mảng từ một đến một trăm phần tử, mỗi phần tử có product_id và quantity bắt buộc |
| Trả về lỗi nếu sai | Không có mã, không có cấu trúc | Trả mã lỗi du_lieu_khong_hop_le kèm danh sách trường sai; không thử lại |
Năm dòng này cho thấy nguyên tắc: một dòng đặc tả phải trả lời được kiểu, đơn vị, phạm vi, bắt buộc và hành vi khi sai. Thiếu một trong năm, bên gọi sẽ tự chọn một cách hiểu.
Cách kiểm tra nhanh: nếu viết mã chỉ dựa vào dòng đặc tả mà vẫn phải đoán, chỗ đó cần viết lại.
Bảng trade-off: ba mức độ chi tiết
| Mức | Nội dung | Chọn khi nào |
|---|---|---|
| Tối thiểu | Mục tiêu, xác thực, danh mục tài nguyên, một ví dụ | API nội bộ, một bên gọi, thay đổi cùng nhịp |
| Tiêu chuẩn | Thêm trường dữ liệu, mã lỗi, phân trang, giới hạn tần suất | Nhiều bên gọi hoặc có ứng dụng di động đã phát hành |
| Đầy đủ | Thêm chính sách phiên bản, nhật ký thay đổi, kiểm thử hợp đồng | Bên gọi ngoài tổ chức hoặc hệ thống đối tác |
Không phải API nào cũng cần mức đầy đủ: viết tài liệu đầy đủ cho API nội bộ một bên gọi là không cần thiết. Nhưng khi có bên gọi ngoài, mức tiêu chuẩn là sàn, không phải trần.
Điểm cần cân nhắc là chi phí ba năm. Tài liệu tối thiểu rẻ hôm nay và đắt dần khi số bên gọi tăng.
Ba chế độ hỏng do tài liệu thiếu
| Triệu chứng | Hệ quả | Cách giảm thiểu |
|---|---|---|
| Đội tích hợp hỏi lại cùng một câu mỗi lần | Mất thời gian cả hai bên, tiến độ trượt | Thêm phần trả lời vào tài liệu, không trả lời riêng trong tin nhắn |
| Dữ liệu sai đơn vị sau khi tích hợp | Phải sửa dữ liệu đã ghi, có thể phải đối soát thủ công | Ghi đơn vị và kiểu trong từng dòng đặc tả, kèm ví dụ số thật |
| Bên gọi sập khi bên nhận đổi nhỏ | Mất doanh thu, mất niềm tin | Có chính sách phiên bản, chỉ thêm trường tuỳ chọn, kiểm thử với bên gọi cũ |
Ba chế độ này đều bắt đầu từ một câu trả lời chỉ tồn tại trong tin nhắn. Không nằm trong tài liệu, câu trả lời sẽ bị hỏi lại, bị hiểu khác hoặc mất khi người đó rời dự án.
Chi phí ba năm khi tài liệu thiếu
Chi phí vận hành. Mỗi lần tích hợp lại cần người hỗ trợ. Số bên gọi tăng thì thời gian người viết API bị chia cho hỗ trợ thay vì phát triển.
Chi phí thay đổi. Không có chính sách phiên bản, không ai biết thay đổi nào an toàn. Kết quả là hoặc không dám đổi, hoặc đổi và gây sự cố. Cả hai đều làm chậm sản phẩm.
Chi phí tuyển dụng và bàn giao. Người mới phải học qua người cũ thay vì qua tài liệu. Thời gian hoà nhập dài hơn, và kiến thức tập trung ở một vài người.
Ba chi phí này không xuất hiện trong hoá đơn nào. Cách nhìn rõ nhất là đếm số câu hỏi lặp lại mỗi tháng: cùng một câu được hỏi nhiều lần nghĩa là tài liệu đang thiếu phần đó.
Đưa tài liệu vào quy trình bốn giai đoạn
Tài liệu thiết kế API nên là sản phẩm của giai đoạn Đặc tả trong quy trình Khám phá, Đặc tả, Xây dựng, Bàn giao và đo lường, không phải việc viết sau khi mã xong.
Khám phá. Ghi lại bên gọi, tình huống sử dụng và tần suất. Phần này quyết định mức chi tiết cần thiết.
Đặc tả. Viết mười hai phần. Đặc tả nên được rà soát bởi một người sẽ là bên gọi, không chỉ bởi người viết.
Xây dựng. Sinh ví dụ từ phản hồi thật đã kiểm thử, thay cho ví dụ viết tay. Cập nhật nhật ký thay đổi mỗi lần phát hành.
Bàn giao và đo lường. Theo dõi số câu hỏi tích hợp và số lỗi theo mã. Hai chỉ số này cho biết phần nào còn thiếu.
Tài liệu phải sống cùng mã. Nếu chỉ viết một lần rồi bỏ, nó sẽ sai dần và thành nguồn gây hiểu nhầm, tệ hơn là không có tài liệu.
Câu hỏi thường gặp
Tài liệu thiết kế API có thể sinh tự động từ mã nguồn không?
Sinh được phần danh mục trường và đường dẫn, nhưng không sinh được mục tiêu, chính sách phiên bản và quy tắc xử lý giá trị lạ. Những phần đó là cam kết, không phải mô tả mã. Cách hợp lý là sinh phần cơ học, viết tay phần cam kết và rà soát định kỳ.
Nên viết tài liệu trước hay sau khi có mã?
Nên viết đặc tả trước khi viết mã, vì đặc tả là công cụ để phát hiện mâu thuẫn. Viết sau thì đặc tả chỉ mô tả những gì đã làm, kể cả sai sót. Tài liệu hướng dẫn và ví dụ có thể hoàn thiện sau, nhưng phần cam kết phải có trước.
Tài liệu dài bao nhiêu là đủ?
Độ dài không phải thước đo; thước đo là số câu hỏi phải hỏi thêm khi tích hợp. Nếu người chưa từng làm với hệ thống đọc tài liệu và viết được lệnh gọi hoàn chỉnh gồm cả xử lý lỗi, tài liệu đã đủ.
Có cần tài liệu riêng cho từng phiên bản API không?
Cần giữ tài liệu của phiên bản còn hỗ trợ, và ghi rõ khác biệt giữa các phiên bản trong nhật ký thay đổi. Bên gọi đang dùng phiên bản cũ cần đọc đúng tài liệu của phiên bản đó. Xoá tài liệu cũ là nguyên nhân phổ biến của lỗi tích hợp.
Cập nhật và kiểm chứng
Cập nhật tháng 11/2026. Nội dung được rà soát theo thực tiễn viết tài liệu giao diện lập trình và nguyên tắc tương thích ngược. Bài viết mang tính tham khảo; mức chi tiết phù hợp cần dựa trên số bên gọi và ràng buộc của hệ thống.
Bài viết liên quan: bảo mật phần mềm là gì, chứng chỉ bảo mật phần mềm, kiến trúc phần mềm là gì và AI coding là gì.
Nếu bạn cần tài liệu API đủ để đội khác tích hợp mà không phải hỏi lại, WinSell xây dựng phần mềm theo yêu cầu theo bốn giai đoạn Khám phá, Đặc tả, Xây dựng, Bàn giao và đo lường — xem dịch vụ của WinSell. Báo giá sau khi chốt phạm vi.
Cần một hệ thống chạy được, không chỉ một bài viết?
WinSell xây phần mềm theo yêu cầu và làm SEO/GEO cho chính sản phẩm đó. Phạm vi và báo giá được chốt sau bước khám phá.
