API mở (Open API)
1. Tổng quan
A. Định nghĩa
API mở (Open API) là một giao diện chuẩn được công khai để các nhà phát triển·dịch vụ bên ngoài có thể truy cập và sử dụng; bằng cách mở dữ liệu·chức năng mà tổ chức nắm giữ, nó thúc đẩy tích hợp·mở rộng dịch vụ và một hệ sinh thái (nền tảng).
Bản chất của API mở nằm ở "hợp đồng" hơn là ở công nghệ. Thông qua lời hứa rằng dù cách hiện thực bên trong thay đổi thế nào, chỉ cần tôn trọng giao diện được công khai ra bên ngoài (định dạng yêu cầu, lược đồ phản hồi, phương thức xác thực), các tổ chức không biết nhau vẫn có thể kết hợp hệ thống mà không cần thương lượng trước. Chính "hợp đồng được chuẩn hóa" này là cốt lõi phân biệt API mở với tích hợp điểm-điểm (Point-to-Point) riêng lẻ.
B. Bối cảnh ra đời và sự cần thiết
Các hệ thống trong quá khứ khép kín, nên để trao đổi dữ liệu với bên ngoài phải phát triển một tích hợp riêng (Point-to-Point) mỗi lần. Nếu có n đối tượng tích hợp, trong trường hợp xấu nhất phải quản lý n×(n−1) kết nối—một sự bùng nổ tổ hợp—và nếu một hệ thống thay đổi thì phải sửa đồng thời mọi tích hợp đã kết nối, tạo gánh nặng bảo trì lớn. Cách này nhanh chóng trở nên kém hiệu quả khi số người tham gia tăng.
Trong nền kinh tế số, giá trị tăng lên khi một dịch vụ kết hợp với nhiều dịch vụ (mashup). Ví dụ như đặt thông tin giao hàng hay bất động sản lên bản đồ, hoặc kết hợp thanh toán·xác thực·bản đồ để tạo dịch vụ mới. API mở biến sự kết hợp này thành một hợp đồng chuẩn, cho phép bất kỳ ai gọi chức năng theo một đặc tả đã định. Nói cách khác, sự cần thiết căn bản của API mở là hạ chi phí tích hợp và tăng tốc độ đổi mới.
Đặc biệt, open banking·MyData của ngành tài chính bắt buộc mở API bằng luật·chế độ, khiến nó trở thành trường hợp tiêu biểu mà API mở vượt qua một lựa chọn công nghệ đơn thuần để thành hạ tầng ngành. Khi thông tin tài khoản·giao dịch từng khép kín theo từng ngân hàng được mở qua API chuẩn, các công ty fintech có thể cung cấp dịch vụ tích hợp dữ liệu của nhiều công ty tài chính trong một ứng dụng. Đây là trường hợp API mở thay đổi chính cấu trúc thị trường.
C. Đặc điểm
Đặc điểm của API mở vừa là giá trị vừa là gánh nặng quản lý của nó. Tính mở·chuẩn·tái sử dụng nuôi lớn hệ sinh thái, trong khi vì ai cũng có thể gọi nên xác thực·tính phí·kiểm soát lưu lượng nhất thiết phải đi kèm. Nghĩa là mệnh đề kép "mở, nhưng có kiểm soát" là bản chất của việc vận hành API mở, và điểm đạt được sự cân bằng này chính là API gateway.
| Đặc điểm | Nội dung | Nhiệm vụ quản lý đi kèm |
|---|---|---|
| Tính mở | Công khai chức năng·dữ liệu cho bên ngoài đã xác thực | Kiểm soát truy cập·quản lý quyền |
| Tính chuẩn | Tuân thủ chuẩn như HTTP·REST·OpenAPI (Swagger) | Quản lý đặc tả·phiên bản |
| Tính tái sử dụng | Mở rộng hệ sinh thái mashup·nền tảng | Cổng nhà phát triển·tài liệu hóa |
| Cần kiểm soát | Kiểm soát xác thực·tính phí·lưu lượng | Vận hành API gateway |
Tính chuẩn đặc biệt là yếu tố quyết định đằng sau sự lan rộng của API mở. Vì có một ngôn ngữ chung—HTTP·JSON·đặc tả OpenAPI—các hệ thống xây bằng ngôn ngữ và nền tảng khác nhau vẫn có thể kết hợp mà không cần adapter riêng. Nếu không có chuẩn, phải thương lượng định dạng cho mỗi lần tích hợp, khiến chính việc mở rộng hệ sinh thái là bất khả thi. Nói cách khác, tính chuẩn là nền tảng chống đỡ cho tính tái sử dụng và tính mở.
2. Kiến trúc và thành phần của API mở
API mở trông có vẻ là một cấu trúc đơn giản trong đó máy khách gọi trực tiếp tài nguyên của máy chủ API, nhưng trong môi trường vận hành thực tế, API gateway đóng vai trò cổng trung tâm, đảm nhận đồng thời xác thực·định tuyến·kiểm soát lưu lượng·ghi nhật ký. Sơ đồ cấu trúc dưới đây cho thấy quá trình một yêu cầu đi qua gateway để được xử lý.
flowchart LR
C["Máy khách (app·dịch vụ)"] -->|Yêu cầu HTTPS| G["API gateway"]
G -->|xác thực·phân quyền| A["Máy chủ xác thực (OAuth)"]
G -->|giới hạn tần suất·định tuyến| S["Máy chủ API (tài nguyên)"]
S -->|truy vấn·xử lý| D[(kho dữ liệu)]
S -->|phản hồi JSON| G
G -->|phản hồi·ghi nhật ký| C
G -.giám sát·thống kê.-> M["Cổng quản lý·phân tích"]
Lý do đặt một gateway là hợp nhất các mối quan tâm xuyên suốt (Cross-cutting Concern). Nếu triển khai xác thực·giới hạn lưu lượng·phiên bản·ghi nhật ký cho từng API riêng lẻ thì sẽ phát sinh trùng lặp và không nhất quán, nên chúng được gom về một nơi—gateway—để áp dụng chính sách một cách nhất quán. Cổng nhà phát triển đóng vai trò cửa tự phục vụ, lập danh mục các API này để nhà phát triển bên ngoài đọc đặc tả, được cấp khóa và dùng ngay.
Các thành phần cốt lõi là tài nguyên (định danh bằng URI), hành vi (phương thức HTTP), biểu diễn (chủ yếu là JSON), token xác thực (OAuth·JWT), và gateway·cổng bao quanh chúng. Kết hợp lại, chúng hoàn thiện hợp đồng "ai gọi cái gì, như thế nào, và nhận phản hồi theo định dạng nào".
Xác thực và phân quyền là cổng của việc vận hành API mở. Chuẩn tiêu biểu, OAuth 2.0, là một cơ chế xác thực ủy quyền cho phép truy cập tài nguyên chỉ bằng một access token được ủy quyền, mà không trao trực tiếp thông tin xác thực (mật khẩu) của người dùng cho ứng dụng bên thứ ba. Luồng dưới đây cho thấy quá trình máy khách nhận token và gọi API.
sequenceDiagram
participant C as Máy khách
participant Auth as Máy chủ xác thực
participant API as Máy chủ tài nguyên (API)
C->>Auth: Yêu cầu xác thực·quyền (scope)
Auth->>C: Cấp access token
C->>API: Yêu cầu tài nguyên kèm token
API->>API: Kiểm token·kiểm quyền
API->>C: Phản hồi JSON
Ưu điểm cốt lõi của cơ chế này là quyền tối thiểu và dễ thu hồi. Vì token mang một phạm vi truy cập (scope) và thời gian hết hạn, dù bị đánh cắp thì phạm vi và thời gian thiệt hại cũng bị giới hạn. Ngoài ra, chỉ cần thu hồi token là có thể rút quyền ngay lập tức, an toàn hơn nhiều so với cách chia sẻ mật khẩu. Trong thực tế, người ta phủ thêm OIDC (OpenID Connect) lên trên để chuẩn hóa cả việc xác thực (đó là ai).
3. So sánh thành phần SOAP và REST
Hai cách hiện thực API mở là SOAP và REST. Khác biệt căn bản là SOAP là một giao thức XML nghiêm ngặt còn REST là một phong cách kiến trúc dùng HTTP nguyên trạng. Khác biệt này tạo ra sự đánh đổi giữa hiệu năng, độ tin cậy và sự tiện lợi phát triển.
SOAP có chuẩn mạnh và, với WS-Security·giao dịch (WS-AtomicTransaction), phù hợp với nơi cần độ tin cậy và bảo mật cao như giao dịch liên ngân hàng. Vì thông điệp được bọc nặng nề trong một XML Envelope và giao diện được định nghĩa nghiêm ngặt bằng WSDL nên hợp đồng rõ ràng, nhưng chi phí phụ trội tương ứng lớn và kém linh hoạt. Ngược lại, REST biểu diễn tài nguyên bằng URI và xử lý bằng các phương thức HTTP (GET·POST·PUT·DELETE) nên nhẹ, dễ mở rộng theo chiều ngang vì phi trạng thái (Stateless), và có thể dùng bộ nhớ đệm HTTP nguyên trạng.
Vì những khác biệt này, phần lớn API công khai ngày nay được cung cấp qua REST (hoặc phương án thay thế của nó là GraphQL). Trong môi trường web·di động, tính nhẹ·bộ nhớ đệm·khả năng mở rộng là ưu thế quyết định. Tuy nhiên, ở tích hợp giữa doanh nghiệp (B2B)·hệ thống cũ cần bảo đảm giao dịch mạnh và bảo mật chuẩn, SOAP vẫn được dùng. Nghĩa là thay vì "REST luôn đúng", phán đoán thực tế là lựa chọn theo yêu cầu (độ tin cậy vs tính nhẹ).
| Phân loại | SOAP | REST |
|---|---|---|
| Khái niệm | Giao thức dựa trên XML | Phong cách kiến trúc dựa trên HTTP |
| Thành phần | Envelope·Header·Body, WSDL, UDDI | Tài nguyên (URI)·phương thức HTTP·biểu diễn (JSON)·phi trạng thái |
| Thông điệp | XML | Chủ yếu JSON |
| Bảo mật·giao dịch | Tích hợp sẵn WS-Security·WS-Transaction | Kết hợp riêng với HTTPS·OAuth, v.v. |
| Đặc điểm | Chuẩn mạnh·giao dịch·độ tin cậy | Nhẹ·khả năng mở rộng·bộ nhớ đệm·Stateless |
| Phù hợp | Doanh nghiệp·độ tin cậy cao·B2B | Web·di động·API công khai |
4. Lỗ hổng và biện pháp ứng phó (OWASP API Security Top 10)
Vì API mở bị phơi ra bên ngoài, chúng đối mặt với các mối đe dọa đặc thù của API khác với ứng dụng web. Phổ biến và chí mạng nhất trong số đó là BOLA (Broken Object Level Authorization, thiếu phân quyền ở cấp đối tượng), một lỗ hổng trong đó xác thực vượt qua nhưng "quyền truy cập dữ liệu của người khác" lại không được kiểm chứng, nên chỉ cần đổi định danh trong URL là truy vấn được thông tin của người khác.
Ví dụ, một người dùng đã đăng nhập đổi /orders/1001 thành /orders/1002 để xem đơn hàng của người khác. Nguyên nhân là xác thực (đó là ai) đã được xác nhận nhưng phân quyền (có được truy cập tài nguyên này không) lại không được kiểm chứng theo từng tài nguyên. Do đó, máy chủ phải kiểm chứng lại quyền sở hữu·quyền truy cập của đối tượng trên mỗi yêu cầu, và không được tin ID mà máy khách gửi nguyên trạng. Lý do BOLA liên tục xếp thứ nhất trong OWASP API Top 10 là vì chức năng vẫn hoạt động bình thường nên không dễ lộ khi kiểm thử và chỉ bị khai thác sau khi triển khai.
Ngoài BOLA, các mối đe dọa chính còn có xác thực yếu (Broken Authentication), phơi lộ dữ liệu quá mức, cạn kiệt tài nguyên (DoS do gọi không giới hạn), injection, và phơi lộ các phiên bản API cũ bị bỏ mặc. Phần lớn trong số này có chung nguyên nhân là "máy chủ đã tin đầu vào của máy khách", nên cốt lõi của việc ứng phó là để máy chủ kiểm chứng độc lập mọi đầu vào·yêu cầu·quyền.
| Lỗ hổng | Nguyên lý | Ứng phó |
|---|---|---|
| Thiếu phân quyền cấp đối tượng (BOLA) | Không kiểm chứng quyền sở hữu đối tượng | OAuth 2.0·JWT + kiểm chứng quyền ở cấp đối tượng |
| Xác thực yếu | Quản lý token·phiên yếu | Xác thực chuẩn (OAuth·OIDC), hết hạn·xoay vòng token |
| Phơi lộ dữ liệu quá mức | Phản hồi chứa trường không cần thiết | Tối thiểu hóa trường phản hồi, kiểm lược đồ |
| Cạn kiệt tài nguyên (DoS) | Gọi không giới hạn·truy vấn hàng loạt | Giới hạn tần suất·hạn ngạch, phân trang |
| Injection | Đầu vào không kiểm chứng bị thực thi như truy vấn | Kiểm tra đầu vào, ràng buộc tham số |
| Quản lý tài sản không đúng | Phơi lộ API bị bỏ mặc·phiên bản cũ | Kiểm kê API·quản lý phiên bản, chặn API đã ngừng |
Thực tế, các sự cố trong đó hàng triệu bản ghi cá nhân bị rò rỉ qua BOLA·phơi lộ dữ liệu quá mức đã lặp lại ở nhiều nền tảng lớn, cho thấy bảo mật API là vấn đề của lớp logic ứng dụng, không phải của tường lửa mạng. Vì tường lửa·WAF không thể phân biệt một lỗ hổng phân quyền chứa bên trong một yêu cầu bình thường đã vượt qua xác thực, bảo mật API nhất thiết phải được nội tại hóa trong logic dịch vụ.
5. Quản lý API (vòng đời)
API mở không kết thúc sau khi công bố; vì người dùng bên ngoài phụ thuộc vào nó, nó phải được quản lý cẩn thận từ thiết kế đến ngừng hoạt động. Đột ngột đổi API sẽ làm hỏng mọi dịch vụ từng dùng nó. Do đó, ở giai đoạn thiết kế, hợp đồng được định trước bằng đặc tả OpenAPI (Contract First, ưu tiên hợp đồng), được công bố·vận hành qua gateway·cổng, và khi ngừng thì đặt thời gian gia hạn đủ dài cùng hướng dẫn di chuyển.
flowchart LR
P["Thiết kế (đặc tả OpenAPI)"] --> B["Công bố (gateway·cổng)"]
B --> O["Vận hành (xác thực·tính phí·giám sát)"]
O --> V["Quản lý phiên bản (tương thích ngược)"]
V --> R["Ngừng (gia hạn·di chuyển)"]
O -.phản hồi.-> P
Điểm nhạy cảm nhất trong vòng đời là quản lý phiên bản. Các thay đổi phá vỡ tương thích ngược (xóa một trường, đổi định dạng phản hồi) được tách sang phiên bản mới (/v2), và phiên bản hiện tại được cho một thời gian gia hạn sau thông báo ngừng (Deprecation) để người dùng có thời gian di chuyển. Không giữ nguyên tắc này sẽ làm sụp đổ niềm tin vào hệ sinh thái mở, khiến nhà phát triển bên ngoài ngần ngại chính việc chấp nhận API.
Ở giai đoạn vận hành, quản lý giám sát và SLA (thỏa thuận mức dịch vụ) rất quan trọng. Người dùng bên ngoài phụ thuộc dịch vụ của họ vào tính sẵn sàng·thời gian phản hồi của API, nên các chỉ số lượng gọi·tỷ lệ lỗi·độ trễ mà gateway thu thập phải được quan sát thường xuyên và các dấu hiệu bất thường phải được phát hiện sớm. Ngoài ra, bằng cách áp dụng phân biệt giới hạn gọi (hạn ngạch) và chính sách tính phí theo cấp sử dụng, một đợt bùng nổ từ một người dùng cụ thể được cách ly để không làm giảm chất lượng của toàn bộ dịch vụ.
| Giai đoạn | Hoạt động |
|---|---|
| Thiết kế | Đặc tả OpenAPI (ưu tiên hợp đồng), chuẩn hóa |
| Công bố | Đăng ký với API gateway·cổng nhà phát triển |
| Vận hành | Xác thực·tính phí·giám sát·kiểm soát lưu lượng |
| Quản lý phiên bản | Duy trì tương thích ngược, tách phiên bản mới |
| Ngừng | Thông báo ngừng·gia hạn·hướng dẫn di chuyển |
6. Chuyên sâu: Xu hướng mới nhất và tiêu chuẩn
Hệ sinh thái API mở đang tiến hóa để đáp ứng các nhu cầu mới trong khi vẫn dựa trên REST. Dưới góc độ Kỹ sư chuyên nghiệp, phải hiểu các xu hướng sau cùng nhau.
- Sự trỗi dậy của GraphQL·gRPC: Trong khi REST trả về một phản hồi cố định theo từng tài nguyên, GraphQL cho phép máy khách truy vấn chỉ các trường nó cần, giải quyết việc truyền dữ liệu quá mức/thiếu (Over/Under-fetching). Ngược lại, trong giao tiếp nội bộ microservice, hiệu năng quan trọng nên gRPC, một giao thức nhị phân dựa trên HTTP/2, đang lan rộng. Nghĩa là API công khai có xu hướng phân hóa thành REST/GraphQL còn giao tiếp nội bộ thành gRPC.
- Nâng cao API gateway·quản lý API (APIM): Vượt qua định tuyến đơn thuần, các APIM thương mại/mã nguồn mở (Kong, Apigee, v.v.) tích hợp xác thực·chính sách·tính phí·phân tích đã trở thành hạ tầng chuẩn và, khi kết hợp với service mesh (Istio), kiểm soát cả lưu lượng nội bộ.
- Áp dụng zero trust·mTLS: Theo nguyên tắc zero trust rằng "ngay cả mạng nội bộ cũng không tin", bảo mật đang được tăng cường theo hướng xác thực lẫn nhau đoạn API bằng mTLS (mutual TLS) và kiểm chứng·ghi nhật ký mọi lệnh gọi.
- Mở rộng chính sách mở trong nước: Việc mở API bắt đầu từ open banking·MyData đang lan sang cổng dữ liệu công, dùng chung thông tin hành chính và hơn thế, với API mở tự khẳng định là hạ tầng cốt lõi của nền kinh tế dữ liệu.
- API-First·tự động hóa tài liệu: Khi văn hóa API-First—thiết kế API là sản phẩm đầu ra ưu tiên hàng đầu khi lập kế hoạch dịch vụ—lan rộng, cách tự động sinh tài liệu·SDK·kiểm thử từ đặc tả OpenAPI để bảo đảm đồng thời tính nhất quán và năng suất đang trở thành chuẩn.
7. Cân nhắc và hàm ý
- Kiểm soát lấy gateway làm trung tâm: Thay vì triển khai xác thực·giới hạn lưu lượng·phiên bản·ghi nhật ký cho từng API riêng lẻ, hãy hợp nhất chúng trong API gateway để áp dụng bảo mật·vận hành nhất quán và giảm gánh nặng cho từng dịch vụ.
- Ưu tiên hợp đồng (Contract First): Cố định đặc tả OpenAPI trước cho phép tự sinh tài liệu·máy chủ giả lập (Mock)·mã máy khách, giúp có năng suất phát triển và phát triển song song front-end/back-end.
- Bảo mật là vấn đề của lớp ứng dụng: Chỉ tường lửa không thể chặn các lỗ hổng logic như BOLA. Phải kiểm chứng quyền ở cấp đối tượng trên mỗi yêu cầu và bảo vệ đoạn đường truyền bằng zero trust·mTLS.
- Quản trị và chiến lược hệ sinh thái: API mở vừa là công nghệ vừa là chiến lược kinh doanh. Mở dữ liệu nào để nuôi lớn hệ sinh thái đối tác nào, và thiết kế tính phí·SLA ra sao, chính là năng lực cạnh tranh của nền tảng. Phải cân nhắc rằng việc mở có thể thay đổi cấu trúc thị trường, như với open banking·MyData.
- Đánh đổi trong lựa chọn tiêu chuẩn: REST·GraphQL·gRPC·SOAP mỗi thứ khác nhau về thế mạnh ở tính nhẹ·linh hoạt·hiệu năng·độ tin cậy. Thay vì "cái gì mới nhất", phải chọn bằng cách cân nhắc tổng hợp đối tượng (công khai/nội bộ), yêu cầu (độ tin cậy/hiệu năng) và năng lực của người dùng; ngay trong một hệ thống, việc trộn các giao thức khác nhau theo từng lớp cũng là phổ biến.
Tài liệu tham khảo
- OWASP API Security Top 10 — https://owasp.org/API-Security/
- OpenAPI Specification (Swagger) — https://spec.openapis.org/oas/latest.html
- Viện Thanh toán & Bù trừ Tài chính Hàn Quốc, Open Banking — https://www.open-platform.or.kr/
Tóm tắt một câu: API mở là một "hợp đồng được công khai" dựa trên các tiêu chuẩn (REST/SOAP·OpenAPI) giúp mở rộng hệ sinh thái mashup·nền tảng, ứng phó với các lỗ hổng API theo OWASP (đặc biệt là BOLA) bằng OAuth·kiểm chứng quyền cấp đối tượng·gateway·giới hạn tần suất, và được vận hành bằng quản lý vòng đời ưu tiên hợp đồng·phiên bản·ngừng cùng zero trust·mTLS như hạ tầng nền tảng của open banking·MyData.