API (Application Programming Interface — giao diện lập trình ứng dụng) là một bộ quy ước công khai cho phép phần mềm này yêu cầu phần mềm khác làm một việc hoặc trả về một dữ liệu, mà không cần biết bên trong phần mềm kia được viết thế nào. Khi phần mềm bán hàng tự đẩy đơn sang phần mềm kế toán, khi website tự hỏi hãng vận chuyển phí giao hàng, phía sau gần như luôn là một lời gọi API.
Với nhà quản lý, cách hiểu hữu ích nhất là: API là một hợp đồng. Nó quy định được hỏi gì, hỏi bằng định dạng nào, ai được hỏi, hỏi bao nhiêu lần, và câu trả lời trông ra sao kể cả khi có lỗi. Chất lượng của hợp đồng đó quyết định việc kết nối hai hệ thống mất hai tuần hay sáu tháng, và quyết định dữ liệu có bị mất âm thầm hay không.
API là một hợp đồng, không phải một sợi dây nối
Ẩn dụ quen thuộc so API với người phục vụ trong nhà hàng: khách không vào bếp, chỉ gọi món theo thực đơn. Ẩn dụ này đúng một nửa. Nửa còn thiếu là thực đơn phải được công bố, ổn định và có giá trị ràng buộc. Nếu nhà hàng đổi tên món mỗi tuần mà không báo, khách quen sẽ gọi sai liên tục. Phần mềm cũng vậy: một API đổi tên trường dữ liệu không báo trước sẽ làm hỏng mọi hệ thống đang phụ thuộc vào nó.
Vì thế, điều cốt lõi của API không nằm ở công nghệ truyền tải mà ở sự tách biệt giữa giao diện và phần cài đặt. Bên cung cấp được tự do viết lại toàn bộ bên trong, đổi cơ sở dữ liệu, đổi ngôn ngữ lập trình, miễn giao diện giữ nguyên. Bên sử dụng chỉ cần tin vào giao diện. Nguyên lý này có từ thời các thư viện phần mềm những năm 1960–1970; điều mới của hai thập niên gần đây là giao diện được mở ra qua mạng, cho phép các công ty khác nhau kết nối với nhau.
Hệ quả quản trị rất cụ thể: khi đánh giá một phần mềm, câu "có API" gần như vô nghĩa. Câu cần hỏi là API đó phủ những nghiệp vụ nào, được cam kết ổn định đến đâu, và nhà cung cấp xử lý thế nào khi phải thay đổi. Một phần mềm có API đọc dữ liệu nhưng không có API ghi dữ liệu thì chỉ dùng được cho báo cáo, không dùng được cho tự động hoá.
Một lời gọi API diễn ra như thế nào
Lấy ví dụ website bán hàng tạo một đơn trên phần mềm quản lý kho. Website gửi một yêu cầu (request) tới một địa chỉ cố định gọi là điểm cuối (endpoint), chẳng hạn đường dẫn dành cho tài nguyên "đơn hàng". Yêu cầu có bốn phần: phương thức cho biết muốn làm gì (GET để đọc, POST để tạo, PUT hoặc PATCH để sửa, DELETE để xoá); tiêu đề mang thông tin xác thực và định dạng; thân chứa dữ liệu đơn hàng, thường viết bằng JSON; và các tham số lọc nếu cần.
Phần mềm kho nhận yêu cầu, kiểm tra quyền, kiểm tra dữ liệu hợp lệ, ghi đơn, rồi gửi lại một phản hồi gồm mã trạng thái và dữ liệu. Mã trạng thái theo chuẩn HTTP là ngôn ngữ chung: nhóm 2xx là thành công (201 nghĩa là đã tạo mới), nhóm 4xx là lỗi phía người gọi (400 dữ liệu sai, 401 chưa xác thực, 403 không đủ quyền, 404 không có tài nguyên, 429 gọi quá nhiều), nhóm 5xx là lỗi phía máy chủ.
Sự phân biệt 4xx và 5xx có giá trị vận hành thật. Lỗi 4xx nghĩa là gửi lại y nguyên vẫn hỏng, phải sửa dữ liệu hoặc quyền. Lỗi 5xx hoặc mất kết nối thì có thể thử lại sau. Một tích hợp tốt phải phân loại được hai nhóm này; một tích hợp tồi thử lại mọi thứ hoặc bỏ qua mọi thứ. Cả hai cách đều sinh ra đơn hàng mất hoặc đơn hàng nhân đôi — hai loại sự cố mà phòng kế toán phát hiện muộn nhất và tốn công dọn nhất.
REST, SOAP, GraphQL và webhook khác nhau ở đâu
Bốn kiểu giao tiếp dưới đây xuất hiện thường xuyên nhất trong hồ sơ kỹ thuật của phần mềm doanh nghiệp. Chúng không loại trừ nhau; một hệ thống lớn thường dùng hai ba kiểu cùng lúc.
| Kiểu | Bản chất | Điểm mạnh | Điểm cần lưu ý |
|---|---|---|---|
| REST | Phong cách kiến trúc do Roy Fielding mô tả trong luận án tiến sĩ năm 2000; mỗi đối tượng là một tài nguyên có địa chỉ, thao tác bằng phương thức HTTP | Phổ biến nhất, dễ học, công cụ hỗ trợ nhiều | Nhiều API tự gọi là REST nhưng không theo đủ nguyên tắc; phải đọc tài liệu cụ thể |
| SOAP | Giao thức trao đổi thông điệp XML có lược đồ chặt chẽ, phổ biến trong ngân hàng, bảo hiểm, cơ quan nhà nước | Hợp đồng rõ ràng, có chuẩn bảo mật và giao dịch đi kèm | Cồng kềnh, khó gỡ lỗi, ít nhà phát triển trẻ quen dùng |
| GraphQL | Ngôn ngữ truy vấn cho phép bên gọi chỉ định chính xác trường dữ liệu cần lấy trong một lần gọi | Giảm số lần gọi và lượng dữ liệu thừa, hợp ứng dụng di động | Khó giới hạn tải và khó lưu đệm hơn; bảo mật truy vấn phức tạp hơn |
| Webhook | Chiều ngược lại: hệ thống nguồn chủ động gọi sang địa chỉ của bạn khi có sự kiện | Nhận thay đổi gần như tức thời, không phải hỏi liên tục | Phải xác thực chữ ký, xử lý gửi trùng và gửi thất bại |
Với bài toán doanh nghiệp, cặp phổ biến nhất là REST cho việc đọc và ghi theo yêu cầu, cộng webhook để được báo khi có thay đổi. Nếu phần mềm chỉ có REST mà không có webhook, hệ thống bên bạn phải định kỳ hỏi "có gì mới không" (polling), tốn tài nguyên và luôn trễ một nhịp.
Xác thực và phân quyền: ai được gọi, được làm gì
Mọi API doanh nghiệp đều phải trả lời hai câu: người gọi là ai (xác thực) và người đó được làm gì (phân quyền). Cách đơn giản nhất là khoá API (API key): một chuỗi bí mật gắn vào mỗi yêu cầu. Khoá API dễ dùng nhưng thường mang toàn quyền và không tự hết hạn; lộ một khoá là lộ cả kho dữ liệu cho tới khi có người phát hiện và thu hồi.
Chuẩn được dùng rộng rãi hơn cho kết nối giữa các tổ chức là OAuth 2.0, công bố năm 2012 dưới dạng tài liệu RFC 6749 của IETF. Ý tưởng chính: thay vì đưa mật khẩu cho phần mềm thứ ba, chủ dữ liệu cấp cho nó một mã truy cập có phạm vi giới hạn (chỉ đọc đơn hàng, không xoá được khách hàng) và có thời hạn ngắn, kèm mã làm mới để xin mã mới. Thu hồi quyền của một ứng dụng không ảnh hưởng các ứng dụng khác.
Ba nguyên tắc quản trị nên áp dụng bất kể kỹ thuật nào: mỗi tích hợp dùng một tài khoản kỹ thuật riêng, không dùng chung tài khoản của nhân viên; cấp quyền tối thiểu đủ làm việc; và lưu khoá trong kho bí mật chứ không viết thẳng vào mã nguồn hay bảng tính. Khi một nhân viên IT nghỉ việc, danh sách khoá cần đổi phải có sẵn, không phải đi tìm.
Năm thuộc tính phân biệt API tốt với API "có cho có"
Tài liệu đặc tả đầy đủ. Chuẩn phổ biến hiện nay là OpenAPI, phát triển từ dự án Swagger và được chuyển cho OpenAPI Initiative năm 2015. Một bản đặc tả tốt liệt kê mọi điểm cuối, mọi trường, kiểu dữ liệu, trường bắt buộc, ví dụ và mã lỗi; từ đó lập trình viên sinh được mã kết nối và môi trường thử.
Chính sách phiên bản rõ ràng. Nhà cung cấp nghiêm túc đánh số phiên bản, cam kết giữ phiên bản cũ trong một khoảng thời gian công bố trước và thông báo khi sắp ngừng. Không có chính sách này, mỗi lần họ nâng cấp là một lần bạn có nguy cơ đứt kết nối.
Giới hạn tốc độ minh bạch. API nào cũng phải chặn số lần gọi để tự bảo vệ. Điều quan trọng là giới hạn được công bố, phản hồi trả mã 429 kèm thời gian nên chờ, để hệ thống bên bạn tự giãn nhịp thay vì bị khoá cứng giữa mùa cao điểm.
Hỗ trợ idempotency. Nghĩa là gửi cùng một yêu cầu hai lần chỉ tạo ra một kết quả. Thường làm bằng một khoá định danh duy nhất kèm mỗi yêu cầu tạo mới. Đây là thứ ngăn một lần mất mạng biến thành hai hoá đơn.
Phân trang và lọc theo thời gian. Đọc mười vạn bản ghi trong một lần gọi sẽ treo cả hai bên. API tốt cho phép lấy theo trang và lọc "các bản ghi thay đổi từ thời điểm X", điều kiện tiên quyết để đồng bộ tăng dần thay vì chép lại toàn bộ mỗi đêm.
Câu hỏi nên đặt trước khi mua một phần mềm "có API"
Đưa danh sách dưới đây vào hồ sơ mời thầu hoặc buổi trình diễn sản phẩm. Câu trả lời mơ hồ ở bất kỳ mục nào đều là chi phí ẩn của dự án tích hợp sau này.
- API phủ những đối tượng nghiệp vụ nào, có cả đọc lẫn ghi không? Xin danh sách cụ thể thay vì câu "đầy đủ".
- Có tài liệu đặc tả công khai và môi trường thử (sandbox) tách khỏi dữ liệu thật không?
- Có webhook cho các sự kiện quan trọng như đơn mới, thanh toán, đổi trạng thái không?
- Giới hạn số lần gọi mỗi phút hoặc mỗi ngày là bao nhiêu, có tính thêm phí khi vượt không?
- Chính sách phiên bản và thời gian báo trước khi thay đổi gây vỡ tương thích là bao lâu?
- Cơ chế xác thực là gì, có phân quyền theo phạm vi, có nhật ký truy cập API cho khách hàng xem không?
- Truy cập API có nằm trong gói đang mua hay phải nâng cấp gói, tính phí theo lượt gọi?
- Khi chấm dứt hợp đồng, có lấy được toàn bộ dữ liệu qua API hoặc bản xuất theo định dạng mở không?
Mục cuối hay bị quên nhất. Một phần mềm dễ đưa dữ liệu vào nhưng khó lấy ra là một hình thức khoá chặt nhà cung cấp, và chi phí thật của nó chỉ lộ ra vào ngày bạn muốn đổi.
Hiểu lầm phổ biến về API và thực tế
Những nhận định dưới đây thường xuất hiện trong các cuộc họp chọn phần mềm và hay dẫn tới dự toán sai.
| Hiểu lầm | Thực tế |
|---|---|
| Có API là kết nối được ngay | API chỉ là đầu nối; vẫn phải ánh xạ dữ liệu, xử lý lỗi, giám sát và bảo trì khi hai bên nâng cấp |
| API là việc của bộ phận IT | Quyết định hệ thống nào là nguồn đúng cho dữ liệu nào, xử lý xung đột ra sao là quyết định nghiệp vụ |
| Kết nối xong là xong | Mỗi tích hợp là một sản phẩm nhỏ cần người chịu trách nhiệm, cảnh báo khi lỗi và ngân sách bảo trì hằng năm |
| API nội bộ không cần bảo mật | Phần lớn sự cố rò rỉ qua API đến từ điểm cuối quên kiểm tra quyền, không phải từ mã hoá yếu |
| Càng nhiều API càng tốt | Mỗi kết nối thêm là một điểm có thể hỏng; số lượng nên đi theo luồng nghiệp vụ thật sự cần tự động |
Điểm chung của các hiểu lầm này là coi API như một tính năng. Cách nhìn đúng hơn là coi mỗi kết nối như một quan hệ hợp đồng dài hạn giữa hai hệ thống, có chi phí thiết lập, chi phí duy trì và rủi ro cần quản trị.
Câu hỏi thường gặp
API và tích hợp khác nhau thế nào?
API là giao diện mà một phần mềm mở ra. Tích hợp là toàn bộ giải pháp nối hai hay nhiều phần mềm: gọi API, chuyển đổi định dạng, ánh xạ mã khách hàng và sản phẩm, xử lý lỗi, thử lại, ghi nhật ký và giám sát. API tốt làm tích hợp dễ hơn nhưng không thay thế phần việc còn lại.
Phần mềm không có API thì có kết nối được không?
Vẫn có cách nhưng kém bền: đọc ghi thẳng vào cơ sở dữ liệu (rủi ro khi nhà cung cấp đổi cấu trúc), trao đổi tệp theo lịch, hoặc dùng robot tự động thao tác trên giao diện. Các cách này nên coi là giải pháp tạm và ghi rõ rủi ro trong hồ sơ dự án.
API công khai có nghĩa là ai cũng truy cập được dữ liệu không?
Không. Công khai ở đây thường chỉ là tài liệu được công bố để đối tác lập trình theo. Mỗi lời gọi vẫn phải mang thông tin xác thực hợp lệ và chỉ truy cập được phạm vi dữ liệu mà chủ tài khoản đã cấp quyền.
Nên chọn khoá API hay OAuth 2.0 cho tích hợp nội bộ?
Khoá API chấp nhận được cho kết nối máy với máy trong nội bộ nếu khoá được giới hạn quyền, lưu trong kho bí mật và đổi định kỳ. Khi có bên thứ ba truy cập dữ liệu thay mặt người dùng, hoặc cần thu hồi quyền theo từng ứng dụng, OAuth 2.0 là lựa chọn an toàn hơn.
Làm sao biết một tích hợp qua API đang chạy đúng?
Cần ba lớp giám sát: cảnh báo khi tỷ lệ lỗi hoặc độ trễ vượt ngưỡng, đối chiếu số lượng bản ghi định kỳ giữa hai hệ thống, và một nơi tập trung các bản ghi bị lỗi để người phụ trách xử lý. Thiếu lớp đối chiếu, lỗi âm thầm có thể kéo dài nhiều tuần.
Chi phí của một tích hợp API gồm những gì?
Gồm công phân tích và ánh xạ dữ liệu, công lập trình và kiểm thử, phí API hoặc gói phần mềm cao hơn nếu có, hạ tầng chạy tích hợp, và chi phí bảo trì hằng năm khi một trong hai bên nâng cấp. Phần bảo trì thường bị bỏ khỏi dự toán ban đầu.