Mở đầu — vì sao bài này quan trọng
Hãy tưởng tượng bạn là một BA (Business Analyst) vừa nhận dự án xây dựng app đặt đồ ăn cho một chuỗi nhà hàng ở TP.HCM. Trong buổi họp đầu tiên, anh kỹ thuật trưởng nói: "Bên mình sẽ gọi REST API của đối tác giao hàng để đẩy đơn, response trả về JSON, mình parse status code rồi cập nhật trạng thái". Cả câu nói đó nếu bạn không hiểu, bạn sẽ gật gù cho qua — và rồi khi viết tài liệu yêu cầu (requirement), bạn sẽ bỏ sót những chi tiết khiến cả team developer phải làm lại.
REST API không còn là chuyện riêng của lập trình viên. Trong gần như mọi dự án phần mềm hiện đại, các hệ thống "nói chuyện" với nhau qua API, và phần lớn các API đó tuân theo phong cách REST. Một BA hiểu REST API sẽ viết được tài liệu tích hợp rõ ràng, hỏi đúng câu hỏi trong buổi họp kỹ thuật, ước lượng được độ phức tạp công việc, và trở thành cầu nối thật sự giữa nghiệp vụ và đội phát triển — chứ không chỉ là người chép lại yêu cầu.
Đây là bài học nền tảng. Nó không đi sâu vào từng chi tiết kỹ thuật (những bài sau sẽ làm việc đó), mà giúp bạn dựng được bức tranh tổng thể: API là gì, REST là gì, và vì sao cách thiết kế này thống trị ngành phần mềm suốt hơn hai thập kỷ. Hãy coi đây là tấm bản đồ trước khi chúng ta đi vào từng con đường nhỏ.
Khái niệm cốt lõi
API là gì?
API viết tắt của Application Programming Interface — tạm dịch là "giao diện lập trình ứng dụng". Nghe học thuật, nhưng bản chất rất đời thường: API là cách để hai hệ thống phần mềm nói chuyện và trao đổi với nhau mà không cần biết bên trong nhau hoạt động thế nào.
Một phép so sánh kinh điển là người phục vụ trong nhà hàng. Bạn (ứng dụng A) ngồi ở bàn, muốn ăn một tô phở. Bạn không xông thẳng vào bếp tự nấu — bạn gọi người phục vụ (API), đọc menu (danh sách những gì bạn được phép yêu cầu), nói "cho một tô phở tái". Người phục vụ mang yêu cầu xuống bếp (hệ thống B), bếp nấu xong, người phục vụ bưng tô phở ra cho bạn. Bạn không cần biết bếp dùng nồi nào, lửa bao nhiêu độ — bạn chỉ cần biết cách gọi món và nhận món.
API chính là "menu + người phục vụ" đó. Nó định nghĩa: bạn được yêu cầu những gì, yêu cầu theo định dạng nào, và bạn sẽ nhận lại cái gì.
Trong thực tế, API có ở khắp nơi. Khi app ngân hàng của bạn hiện số dư, nó đang gọi API của hệ thống core banking. Khi bạn đăng nhập một website bằng tài khoản Google, website đó đang gọi API của Google. Khi shipper Grab nhận đơn, app Grab đang gọi hàng loạt API để định vị, tính giá, gán tài xế.
Web API và mô hình Client–Server
Loại API mà BA gặp nhiều nhất là Web API — API hoạt động qua mạng internet bằng giao thức HTTP (giao thức nền tảng của web). Trong mô hình này luôn có hai vai:
- Client (bên gọi): là bên đưa ra yêu cầu. Có thể là app điện thoại, trình duyệt web, hoặc một hệ thống khác.
- Server (bên phục vụ): là bên nhận yêu cầu, xử lý và trả về kết quả.
REST là gì?
REST viết tắt của Representational State Transfer — một phong cách kiến trúc (architectural style) do Roy Fielding đề xuất trong luận án tiến sĩ năm 2000. Lưu ý chữ "phong cách": REST không phải một công nghệ, không phải một thư viện bạn cài đặt, không phải một chuẩn bắt buộc. Nó là một tập hợp các nguyên tắc thiết kế. Khi một API được thiết kế tuân theo các nguyên tắc này, người ta gọi nó là RESTful API.
Ý tưởng cốt lõi của REST rất đẹp: hãy coi mọi thứ trong hệ thống là tài nguyên (resource) — một khách hàng, một đơn hàng, một sản phẩm — và mỗi tài nguyên có một địa chỉ riêng (URL). Bạn thao tác lên các tài nguyên đó bằng những hành động chuẩn của HTTP (lấy về, tạo mới, cập nhật, xóa). Cách tiếp cận này khiến API trở nên dễ hiểu, dễ đoán và nhất quán.
Ví dụ, với tài nguyên "đơn hàng" của một sàn thương mại điện tử:
- Muốn xem danh sách đơn hàng: gọi tới địa chỉ
/orders - Muốn xem chi tiết đơn hàng số 1024: gọi tới
/orders/1024 - Muốn tạo đơn mới: gửi dữ liệu tới
/orders
Các nguyên tắc chính của REST
REST được định nghĩa bởi sáu ràng buộc (constraints). Ở bài nền tảng này, tôi sẽ giới thiệu chúng ở mức tổng quan để bạn có khái niệm — bài 6 sẽ đào sâu từng nguyên tắc của Fielding. Hai nguyên tắc bạn cần nhớ kỹ ngay từ bây giờ:
1. Stateless (phi trạng thái) — Đây là nguyên tắc quan trọng nhất với một BA. Stateless nghĩa là mỗi request phải độc lập và tự chứa đủ thông tin để server xử lý. Server không ghi nhớ gì về các request trước đó của bạn.
Hãy hình dung bạn gọi điện đến tổng đài chăm sóc khách hàng của một nhà mạng, nhưng mỗi lần gọi lại gặp một nhân viên khác và họ hoàn toàn không nhớ cuộc gọi trước. Vậy nên mỗi lần gọi, bạn phải tự khai lại số thuê bao, tự nói rõ vấn đề. Bất tiện cho con người, nhưng với hệ thống thì đây lại là ưu điểm cực lớn: vì server không phải "nhớ" ai cả, nên bạn có thể đặt hàng chục server giống hệt nhau và request nào rơi vào server nào cũng được xử lý như nhau. Điều này giúp hệ thống dễ mở rộng (scale) khi lượng người dùng tăng vọt.
Hệ quả thực tế: vì stateless, mỗi request cần tự mang theo thông tin xác thực (ai đang gọi, có quyền không). Đó là lý do bạn sẽ thấy mỗi request đính kèm "token" hay "API key" — chủ đề của các bài về authentication sau này.
2. Client–Server tách biệt — Bên giao diện (client) và bên xử lý dữ liệu (server) phát triển độc lập. Đội làm app mobile và đội làm backend có thể làm việc song song, miễn là họ thống nhất với nhau "menu" — tức là hợp đồng API (API contract).
3. Uniform Interface (giao diện đồng nhất) — Mọi tài nguyên được truy cập theo một cách thống nhất, có thể đoán trước, như ví dụ /orders/1024 ở trên.
4. Cacheable (có thể lưu đệm) — Response có thể được đánh dấu để lưu tạm, giúp giảm tải và tăng tốc.
Ba nguyên tắc còn lại (Layered System, Code on Demand) sẽ được nói rõ ở bài 6. Bây giờ bạn chỉ cần ghi nhớ tinh thần: REST = tài nguyên + địa chỉ URL + hành động chuẩn HTTP + mỗi request độc lập.
Tình huống thực tế
Tình huống 1: Tích hợp cổng thanh toán cho sàn TMĐT
Một startup TMĐT tại Hà Nội — tạm gọi là "ChợViệt" — cần cho phép khách thanh toán qua ví điện tử MoMo. BA của dự án nhận yêu cầu "tích hợp thanh toán MoMo".
Khi đọc tài liệu kỹ thuật của MoMo, BA thấy đó là một REST API. Để tạo một giao dịch, hệ thống ChợViệt (đóng vai client) gửi một request tới địa chỉ API của MoMo (đóng vai server), kèm theo thông tin: số tiền, mã đơn hàng, đường link để MoMo gọi lại khi thanh toán xong. MoMo trả về một response chứa link thanh toán để chuyển hướng khách hàng.
Điều thú vị nằm ở tính stateless: mỗi request tạo giao dịch của ChợViệt phải tự mang đầy đủ thông tin và chữ ký bảo mật. MoMo không "nhớ" rằng vừa nãy ChợViệt đã hỏi gì. Vì thế BA phải mô tả rõ trong tài liệu: với mỗi giao dịch, hệ thống cần gửi đủ những trường nào.
Bài học rút ra: Hiểu mô hình client–server và stateless giúp BA viết tài liệu tích hợp chính xác, biết phải làm rõ với đối tác những thông tin gì cần đính kèm trong từng request, thay vì giả định "hệ thống tự nhớ".
Tình huống 2: App giao hàng và việc đẩy đơn sang đối tác
Quay lại app đặt đồ ăn ở đầu bài. Chuỗi nhà hàng muốn khi khách đặt món, đơn sẽ tự động được đẩy sang đối tác giao hàng (giả định là "GiaoNhanh") để có shipper đến lấy.
BA ngồi với team kỹ thuật và phác ra luồng REST: hệ thống nhà hàng tạo một đơn giao hàng bằng cách gửi request tới /deliveries của GiaoNhanh, kèm địa chỉ lấy hàng, địa chỉ giao, số điện thoại khách. GiaoNhanh trả về một response chứa mã vận đơn, ví dụ GN-88231. Sau này, muốn kiểm tra trạng thái đơn đó, hệ thống chỉ cần gọi /deliveries/GN-88231.
Nhờ tư duy REST — mỗi đơn giao hàng là một tài nguyên có địa chỉ riêng — BA mô tả được rõ ràng các luồng: tạo đơn, tra cứu đơn, hủy đơn, mỗi luồng tương ứng một thao tác trên tài nguyên deliveries. Tài liệu nhờ vậy mạch lạc, developer đọc là hiểu ngay.
Bài học rút ra: Tư duy "mọi thứ là tài nguyên có địa chỉ riêng" giúp BA cấu trúc tài liệu nghiệp vụ theo đúng cách hệ thống vận hành, giảm hiểu lầm giữa nghiệp vụ và kỹ thuật.
Tình huống 3: Vì sao stateless cứu một đợt khuyến mãi lớn
Một sàn bán lẻ ở Đông Nam Á tổ chức flash sale ngày 9/9. Bình thường hệ thống chạy 4 server, nhưng dịp này họ dự kiến lượng truy cập tăng gấp 20 lần. Đội kỹ thuật quyết định tạm thời tăng lên 60 server trong vài giờ cao điểm.
Điều này khả thi chính vì API của họ thiết kế theo REST và stateless. Vì không server nào phải "nhớ" người dùng cụ thể, nên bất kỳ request nào của bất kỳ ai cũng có thể rơi vào bất kỳ server nào trong số 60 server đó mà vẫn được xử lý đúng. Thêm hay bớt server chỉ là chuyện vài phút. Nếu hệ thống là stateful (server phải nhớ phiên làm việc của từng người), việc nhân bản server lên 60 cái sẽ là cơn ác mộng đồng bộ dữ liệu.
BA của dự án, khi tham gia ước lượng năng lực hệ thống cho sự kiện, hiểu được vì sao team kỹ thuật tự tin "scale ngang" dễ dàng — và truyền đạt lại điều đó cho ban lãnh đạo một cách thuyết phục.
Bài học rút ra: Nguyên tắc stateless không chỉ là lý thuyết — nó là lý do hệ thống REST mở rộng được dễ dàng. Một BA hiểu điều này sẽ tham gia tốt hơn vào các quyết định liên quan đến hiệu năng và quy mô.
Hướng dẫn từng bước
Khi bạn — với tư cách BA — lần đầu tiếp cận một REST API (ví dụ đọc tài liệu của một đối tác để chuẩn bị tích hợp), hãy đi theo các bước sau:
- Xác định các tài nguyên (resource) chính. Đọc tài liệu và liệt kê các "danh từ nghiệp vụ" mà API thao tác: khách hàng, đơn hàng, sản phẩm, giao dịch... Đây chính là các tài nguyên. Việc này giúp bạn ánh xạ API với các thực thể nghiệp vụ mà bạn đã quen.
- Xác định địa chỉ (endpoint) của từng tài nguyên. Với mỗi tài nguyên, tìm xem nó nằm ở URL nào, ví dụ
/customers,/orders. Ghi chú lại để dùng trong tài liệu.
- Xác định client và server trong luồng của bạn. Trong kịch bản tích hợp này, hệ thống của bạn là bên gọi (client) hay bên cung cấp (server)? Điều này quyết định bạn cần viết tài liệu cho ai và mô tả theo hướng nào.
- Kiểm tra yêu cầu xác thực. Vì REST là stateless, mỗi request thường cần thông tin xác thực đính kèm. Tìm trong tài liệu xem API yêu cầu API key, token hay cách nào khác. Ghi lại để team chuẩn bị.
- Liệt kê thông tin cần gửi và nhận cho mỗi luồng nghiệp vụ. Với từng nghiệp vụ (tạo đơn, tra cứu, hủy...), ghi rõ: cần gửi đi những trường gì, sẽ nhận về những gì. Đây là cốt lõi của tài liệu tích hợp.
- Phác họa luồng end-to-end bằng ngôn ngữ nghiệp vụ. Cuối cùng, viết lại toàn bộ luồng theo cách người không chuyên kỹ thuật cũng hiểu: "Khi khách đặt món, hệ thống gọi tới đối tác giao hàng để tạo đơn, nhận về mã vận đơn, lưu lại để tra cứu về sau."
Lỗi thường gặp & mẹo
Lỗi 1: Nhầm REST với HTTP hoặc với JSON. Nhiều người mới nghĩ "REST nghĩa là dùng HTTP và trả JSON". Không hẳn. REST là phong cách thiết kế; HTTP là giao thức truyền tải; JSON là định dạng dữ liệu. Một API có thể dùng HTTP nhưng không hề RESTful. Hãy phân biệt rạch ròi ba khái niệm này.
Lỗi 2: Cho rằng server "nhớ" mình. Đây là lỗi tư duy phổ biến nhất. Vì REST stateless, đừng bao giờ viết tài liệu kiểu "sau khi đăng nhập, các bước sau hệ thống tự biết người dùng là ai". Mỗi request cần tự mang theo thông tin định danh. Bỏ qua điều này dẫn đến tài liệu sai và developer hiểu nhầm.
Lỗi 3: Coi "API" và "REST API" là một. REST chỉ là một trong nhiều phong cách. Còn có SOAP, GraphQL, gRPC... (các bài sau sẽ đề cập). Khi đối tác nói "API", hãy hỏi rõ đó là loại nào để chuẩn bị đúng.
Mẹo 1: Tập thói quen đọc URL của API như đọc một câu. /orders/1024/items nghĩa là "các món hàng (items) thuộc đơn hàng số 1024". Cấu trúc URL của REST kể cho bạn nghe câu chuyện nghiệp vụ.
Mẹo 2: Khi mô hình hóa nghiệp vụ, hãy nghĩ theo "danh từ" (tài nguyên) trước, "động từ" (hành động) sau. Đây đúng là cách tư duy REST, và nó rất khớp với cách BA vốn đã quen mô hình hóa thực thể nghiệp vụ.
Mẹo 3: Đừng ngại hỏi team kỹ thuật câu "API này là client hay server trong luồng của mình?". Câu hỏi tưởng đơn giản này giúp tránh vô số hiểu lầm về sau.
Bài tập thực hành
- Nhận diện API trong đời sống. Liệt kê 3 app bạn dùng hằng ngày (ví dụ ứng dụng ngân hàng, Grab, Shopee) và với mỗi app, đoán xem nó đang gọi API của những hệ thống bên ngoài nào. Ghi rõ trong tình huống đó app là client hay server.
- Phân biệt khái niệm. Viết bằng lời của bạn (mỗi câu một dòng) sự khác nhau giữa: API, REST, HTTP, JSON. Mục tiêu là giải thích cho một đồng nghiệp không chuyên kỹ thuật hiểu được.
- Thiết kế tài nguyên. Giả sử bạn làm BA cho một app quản lý phòng gym. Hãy liệt kê ít nhất 4 tài nguyên (resource) chính của hệ thống và đề xuất địa chỉ URL theo phong cách REST cho mỗi tài nguyên (ví dụ
/members).
- Giải thích stateless. Dùng một ví dụ đời thường của riêng bạn (không trùng ví dụ tổng đài trong bài) để giải thích nguyên tắc stateless cho một người mới. Sau đó nêu một lợi ích thực tế mà stateless mang lại.
- Đọc tài liệu thật. Tìm trên mạng tài liệu công khai của một API quen thuộc (ví dụ API thời tiết, hoặc tài liệu nhà phát triển của một ví điện tử Việt Nam). Xác định: đâu là các tài nguyên, đâu là endpoint, API có yêu cầu xác thực không.
Tóm tắt
Trong bài đầu tiên này, chúng ta đã dựng được tấm bản đồ tổng thể:
- API là cách hai hệ thống phần mềm trao đổi với nhau mà không cần biết bên trong nhau hoạt động thế nào — như người phục vụ kết nối bạn với nhà bếp.
- Web API hoạt động qua HTTP theo mô hình client–server: client gửi request, server trả response.
- REST là một phong cách kiến trúc (không phải công nghệ), trong đó mọi thứ được coi là tài nguyên có địa chỉ URL riêng, được thao tác theo cách nhất quán, dễ đoán.
- Nguyên tắc nền tảng quan trọng nhất với BA là stateless: mỗi request độc lập, tự chứa đủ thông tin, server không ghi nhớ request trước. Đây là chìa khóa giúp hệ thống REST mở rộng dễ dàng.
- Đừng nhầm lẫn API ≠ REST ≠ HTTP ≠ JSON — bốn khái niệm khác cấp độ.