- Trong bài báo nền tảng về REST của Roy Fielding, việc dùng các phương thức HTTP hay API xoay quanh CRUD không được quy định rõ là bắt buộc; REST ban đầu nhấn mạnh thiết kế hệ thống dựa trên hypermedia (HATEOAS)
- Nhiều thứ mà mọi người gọi là API RESTful thực tế không triển khai các ràng buộc REST quan trọng (đặc biệt là việc sử dụng hypermedia)
- Tài nguyên không chỉ giới hạn ở cấu trúc dữ liệu hay thực thể đơn thuần, mà bao gồm mọi khái niệm có thể được định danh bằng URI
- Theo 6 quy tắc của Fielding, các điểm cốt lõi là điều hướng lấy hypermedia làm trung tâm, tính độc lập với giao thức và sự coi trọng media type
- Trong thực tế, do sự tiện lợi của các công cụ tài liệu hóa như OpenAPI, phần lớn API có xu hướng được thiết kế gần với kiểu RPC hơn là RESTful thực sự
Vì sao phần lớn API RESTful không thật sự RESTful
- Bài báo tiêu biểu (2000) của Roy Fielding trình bày REST (Representational State Transfer) như một phong cách lý tưởng cho thiết kế phần mềm dựa trên mạng, đồng thời giải thích đây là nguyên lý đứng sau thành công của web
- Bài báo không quy định việc dùng phương thức HTTP hay thiết kế xoay quanh CRUD là bắt buộc; thay vào đó nhấn mạnh rằng khi hướng tới REST, trọng tâm là chuyển trạng thái dựa trên hypermedia (HATEOAS), giao diện thống nhất và tương tác lấy tài nguyên làm trung tâm
Những hiểu lầm về hypermedia (HATEOAS) và REST
- Fielding chỉ rõ rằng API không có hypermedia thì không phải RESTful
- "Nếu engine không được điều khiển bởi hypertext thì đó không phải RESTful"
- HATEOAS là cách mà client khám phá hành động một cách động bằng cách đi theo các liên kết được nhúng trong phản hồi từ server
- Việc chỉ dùng giao diện HTTP/CRUD đơn thuần là khác với bản chất của REST
Những hiểu lầm phổ biến về REST
- Nghĩ rằng REST là CRUD (trong khi thực tế là khái niệm rộng hơn nhiều)
- Hiểu nhầm rằng tài nguyên là thực thể (cấu trúc dữ liệu trên server)
- Cho rằng API RESTful không được dùng động từ (Verb)
- Những điều này chỉ là quyết định thiết kế, không liên quan trực tiếp đến bản chất của REST
Ý nghĩa thực sự của điều hướng bằng hypermedia (HATEOAS)
- Mục tiêu của HATEOAS là giảm thiểu mức độ ràng buộc giữa client và server
- Khi cấu trúc URI của server thay đổi, nó giúp giảm bớt nỗi đau phải triển khai lại client, từ đó tăng khả năng mở rộng và tiến hóa
- Client khám phá hành động bằng cách đi theo các hyperlink trong phản hồi mà không cần tài liệu hay kiến thức có sẵn
{
"orderId": 123,
"\_links": {
"self": { "href": "/orders/123" },
"cancel": { "href": "/orders/123/cancel", "method": "POST" }
}
}
- Như ví dụ trên, chỉ khi phản hồi bao gồm hành động (liên kết) thì mới tiến gần tới RESTful đúng nghĩa
Tài nguyên trong REST là gì?
- Tài nguyên là bất cứ thứ gì có thể được định danh bằng URI
- Bao gồm tài liệu, hình ảnh, vật thể vật lý, dịch vụ, khái niệm trừu tượng, v.v.
- Trên server không hẳn tồn tại một "tài nguyên" vật lý; chỉ có một cấu trúc ánh xạ trừu tượng có thể truy cập qua URI
- Ngay cả trong RFC 3986, phạm vi của tài nguyên cũng không bị giới hạn
- Có thể bao gồm tài liệu điện tử, hình ảnh, nguồn thông tin, dịch vụ, thậm chí cả con người, pháp nhân hoặc sách
6 quy tắc của API RESTful theo định nghĩa của Fielding
- 1. Không phụ thuộc vào một giao thức duy nhất
- Việc định danh dựa trên URI phải có thể được sử dụng trên mọi giao thức
- 2. Không tùy tiện thay đổi chuẩn của giao thức (ví dụ: HTTP)
- Có thể bù đắp những thiếu sót của chuẩn, nhưng không được tự ý thêm hoặc thay đổi quy tắc
- 3. Tập trung vào việc định nghĩa media type (định dạng) thay vì cấu trúc URI
- Tập trung vào định dạng dữ liệu và định nghĩa liên kết, không lãng phí công sức vào việc đặc tả/tài liệu hóa đường dẫn
- 4. Không hardcode cách đặt tên URI hay cấu trúc phân cấp cố định
- Không để client suy đoán hay cố định cấu trúc namespace của server, mà dẫn dắt bằng điều hướng dựa trên liên kết
- 5. Không để lộ loại tài nguyên (phân loại nội bộ)
- Kiểu đối tượng nội bộ không có ý nghĩa với client; chỉ nên để lộ media type và liên kết chuẩn
- 6. Chỉ cần bookmark (URI ban đầu), phần còn lại phải được khám phá qua các liên kết trong phản hồi
- Client chỉ cần biết media type chuẩn, còn mọi chuyển trạng thái phải luôn dựa trên các hyperlink trong phản hồi từ server
Diễn giải các quy tắc và cách áp dụng thực tế
- Cần giảm thiểu sự ràng buộc với giao thức, URI và kiểu dữ liệu thì mới tiến gần tới RESTful đúng nghĩa
- API nên tập trung vào định dạng của dữ liệu và liên kết (media type); client không cần biết trước cấu trúc URI hay quy tắc đặt tên
- Thay vì đặc tả sẵn các đường dẫn như
/users/123/activate, nên hướng dẫn hành động bằng liên kết "activate" trong phản hồi
Vì sao API RESTful thực sự lại hiếm
- Sự tiện lợi của các công cụ như OpenAPI, Swagger thường được ưu tiên trong môi trường phát triển
- Mang lại các lợi ích thực tế như tự động tạo tài liệu, sinh mã và kiểm tra tính hợp lệ
- Trong môi trường SPA nơi client và server do cùng một nhóm phát triển, nhu cầu giải quyết vấn đề ràng buộc URI không quá lớn, nên ưu điểm của HATEOAS không nổi bật
- Gánh nặng học tập ban đầu của các nguyên tắc REST, cùng với độ phức tạp của việc phân tích liên kết động, tạo ra rào cản thực tiễn đáng kể
Kết luận
- Theo các quy tắc của Fielding, một API RESTful đúng nghĩa bắt buộc phải có điều hướng động dựa trên hypermedia (HATEOAS)
- REST không đơn giản là triển khai CRUD trên HTTP; đó là một kiến trúc tập trung vào liên kết lỏng lẻo, khả năng tiến hóa và chuyển trạng thái động, tương tự các nguyên lý của web
- Trong thực tế, tính thực dụng và bối cảnh của đội ngũ có thể quan trọng hơn
- Nếu là public API dành cho các nhà phát triển bên ngoài thì nên cân nhắc áp dụng HATEOAS, nhưng nếu là API chỉ dùng nội bộ thì kiểu RPC đơn giản cũng có thể thực dụng hơn
- Điều cốt lõi là thiết kế API sao cho dễ học và khó bị dùng sai, chứ không nhất thiết phải là RESTful
1 bình luận
Ý kiến trên Hacker News
Tôi đồng cảm với sự chống lại chủ nghĩa nguyên tắc thái quá ở đây và cũng thấy bài luận văn của Fielding rất thú vị, nhưng tôi cảm giác đây là cuộc chiến đã kết thúc từ lâu. Chỉ cần nghe đến cụm từ REST API là gần như có thể chắc chắn rằng
kiểu hàm như thế này, và hàm đó gọi
Ở backend lại có hàm kiểu
rồi mô tả ánh xạ URL bằng annotation. Rốt cuộc đây vẫn là RPC. Chỉ là thay vì một hệ thống phức tạp và thiếu trực quan, nó tồn tại dưới dạng thủ công hơn và lập trình viên kiểm soát được hơn. 80% vấn đề của phần lớn mọi thứ là do người ta không dùng định dạng ngày ISO 8601
Tôi không thật sự hiểu vì sao ai đó lại coi đây là một "trận chiến" và bận tâm đến vậy. Khái niệm REST có ích, nhưng phần HATEOAS hầu như không thực tế và chỉ tạo thêm vấn đề. Nếu nhìn vào Richardson maturity model thì đỉnh cao của REST có bao gồm những yếu tố như HATEOAS. Tôi cũng không hiểu lập luận rằng bỏ HATEOAS ra thì không thể gọi là REST, vì đó cũng chẳng phải khác biệt quá lớn. Nếu HATEOAS trên thực tế gần như vô nghĩa thì việc chấp niệm với kiểu phân loại mang tính nguyên tắc này có vẻ cũng không có ý nghĩa mấy. Richardson maturity model
Ở đoạn "các nhóm tranh cãi quá mức về mã trạng thái và thường dùng khác với HTTP spec", tôi muốn nhấn mạnh rằng 401 Unauthorized nên dùng cho trường hợp chưa xác thực, còn 403 Forbidden nên dùng cho trường hợp không có quyền
Tôi thường hỏi mọi người xem họ có thực sự định dùng nghĩa của REST như được định nghĩa trong bài báo không. Tôi thường không chấp nhận việc lạm dụng những thuật ngữ vô nghĩa. Cuối cùng tôi chỉ nói kiểu "à, vậy là web API thôi mà" rồi bỏ qua. Điểm khác biệt quan trọng là với mỗi API kiểu này, ta phải xác định xem nó có điểm kỳ quặc gì
Với tôi, sắc thái thật sự quan trọng là, các "hypermedia link" trông có vẻ như là thứ "tổng quát" nhờ nhiều link type khác nhau (trong HTTP header hoặc trong dữ liệu trả về), nhưng trên thực tế REST ngày nay cũng hoạt động y hệt vậy. Ví dụ, nếu thiết kế sai và lẽ ra phải là "enable" chứ không phải "activate", thì cuối cùng bạn vẫn phải đổi từ /api/v1/account/ID/activate sang /api/v2/account/ID/enable. Tức là bạn vẫn phải hardcode ý nghĩa của mọi action ở đâu đó trong API (và còn thiếu cả metadata phụ như icon, bản dịch mô tả action, v.v.). Tính "tổng quát" của cách này thật ra chỉ là ảo tưởng
Khi lần đầu tiên phải phát triển HTTP API cách đây 13 năm, tôi đã đọc bài luận văn của Fielding từ đầu đến cuối để hiểu REST thật sự là gì, rồi còn đọc cả RESTful Web Services Cookbook. Sau đó tôi né các quy ước của Django để làm một REST API. Đó là một kiểu tiếp cận khá "cargo cult", vì tôi thật ra không biết REST thật sự mang lại lợi ích gì cho dịch vụ của chúng tôi. Mãi vài năm sau, khi đã xây nhiều HTTP API khác nhau hơn, tôi mới nhận ra rằng trong thực tế công việc, lý thuyết REST không đem lại lợi ích nào cả. Tầm nhìn về "self-discovery" và "tương thích với generic client" gần như là bất khả thi, và cụ thể thì bài luận văn của Fielding cũng hoàn toàn không chỉ dẫn đầy đủ về những phần đó. Muốn tạo ra một API thực sự self-discoverable thì cần các quy tắc cụ thể như "giao thức khám phá endpoint", "mô tả thao tác", "thông điệp trợ giúp", v.v. Và rồi cuối cùng bạn vẫn phải tạo một client chuyên biệt hiểu các quy tắc đó, thế là lợi thế của generic client biến mất. Tức là trong thực tế, với API/JS code/CLI chuyên cho từng dịch vụ, rốt cuộc vẫn chỉ còn cách viết mã tùy biến cho từng server. Hơn nữa, UX tốt lại xung đột với lý tưởng của REST, vì muốn UX thật sự tốt thì phải viết code chuyên biệt cho ứng dụng ở phía frontend. Các thành phần UI cũng có thể tiêu chuẩn hóa, nhưng trên thực tế việc tạo UI linh hoạt bằng ngôn ngữ như JavaScript lại hữu ích hơn nhiều
Tôi đồng cảm với giới hạn của khái niệm API self-discoverable. Một REST client thật sự về cơ bản là không thể triển khai. Nó phải biết hành vi của mọi URL, và nếu có hành vi mới được thêm vào (ví dụ: /cansofspam/123/frobnicate) thì client không thể xử lý rõ ràng. Cuối cùng либо phải cập nhật client, либо bỏ qua, hoặc chỉ có thể thêm một nút cực kỳ đơn giản (ví dụ: Frobnicate). Vì vậy trên thực tế không tồn tại REST server hay client theo nghĩa đầy đủ. Thực tế vận hành là client chỉ hỗ trợ API mà nó đã kỳ vọng từ trước, không cần discovery
API có nhiều khía cạnh nên rất khó mô tả đầy đủ. Người dùng API còn cần biết độ trễ phản hồi trung bình, mã lỗi có thể retry, tính nguyên tử/tính idempotent của action, v.v. Chỉ HATEOAS thôi thì không thể nói lên những điều đó. Không cần phải triển khai REST hoàn hảo, và về cơ bản lợi ích của REST chỉ là có một ngôn ngữ thống nhất để ánh xạ danh từ/động từ vào HTTP method và URL. Nhưng ngay cả vậy vẫn còn vô số chi tiết thiết kế và cân nhắc. Ví dụ có những thứ HTTP spec cho phép nhưng LB thực tế lại không dùng được, hoặc phải cân nhắc tiêu chí retry lỗi 500 / logic backoff, v.v.
Trình duyệt mới chính là "generic code", thứ cung cấp UX tốt nhất mà chúng ta dùng hằng ngày. Khái niệm REST cũng bao gồm việc server có thể chuyển code cho client (dù có vấn đề bảo mật, nhưng trình duyệt và các tiêu chuẩn đã xử lý được khá nhiều phần này). Liên kết tới phần liên quan trong luận văn của Fielding
Thật ra ngay cả định nghĩa REST ở phiên bản nới lỏng hơn cũng chẳng đem lại bao nhiêu lợi ích. Việc "phải dùng DELETE để xóa resource" không quan trọng lắm. Cứ dùng POST thì có ai thấy khó khăn gì đâu?
Tôi chưa bao giờ nghĩ "self-discoverable" là mục tiêu, và cũng không cho rằng đó là điều khả thi. Với thiết kế client đơn giản thì kỳ vọng đó ngay từ đầu đã quá cao rồi. Đặc biệt là ngay cả trong TFA, từ "discoverable" cũng không hề xuất hiện
Kiểu thiết kế API này thực sự hữu ích ở những nơi người dùng và agent thay họ khám phá (ví dụ: trình duyệt) có thể duyệt qua API và tương tác dựa trên media type, thông tin link trong từng phản hồi. Phần lớn web API không phục vụ use-case đó, mà được thiết kế cho web app theo đuổi một UI/UX cụ thể. Đó là hướng đi được chọn có chủ đích. Người làm app muốn kiểm soát hoàn toàn cách biểu diễn dữ liệu, luồng UI, v.v. để phục vụ mục tiêu của ứng dụng. Thiết kế REST API cần thiết hơn khi người dùng phải chủ động kiểm soát cách sử dụng resource của API. Ví dụ như
Thực ra tài liệu HTML chính là ví dụ đó. Bên trong tài liệu có link sang các tài liệu khác, và người dùng có thể điều hướng đi đâu cũng được theo phần chữ ghi trên link. Nếu dành cho người dùng thì ta gọi là UI, còn nếu dành cho ứng dụng thì gọi là API. Lý do HATEOAS nghe kỳ quặc là vì nó khiến người ta có cảm giác như đang cố làm API trực tiếp cho người dùng. Nhưng thực ra chúng ta đã có điều đó rồi dưới dạng UI
Khái niệm REST thuần túy rất nặng tính học thuật. Ngay cả trong các dự án open data/big data, để xây dựng hiệu năng hay kiến trúc thực sự hữu dụng thì cách tiếp cận thực tế vẫn quan trọng hơn việc có đạt REST hay không. Ngay cả giới học thuật cuối cùng cũng phải tạo ra sản phẩm, nên họ cũng không cố chấp với REST hoàn hảo
Kiểu thiết kế API này hữu ích không chỉ cho web page mà còn khi xây dựng các client khác. Có thể lấy resource bằng GET, trích xuất giá trị từ field/path, tạo URI mới để thao tác, v.v. rồi xây nhiều app/CLI/UI theo các mẫu tương tự. Nếu là non-SPA thì cũng có thể triển khai trực tiếp bằng HTML, và về bản chất người dùng (hoặc user-agent) đang dereference thông tin bên trong biểu diễn được trả về
Tôi tự hỏi khi thời đại AI tiêu thụ API đến, use-case này có trở nên quan trọng hơn không. Khả năng discoverability của API có lợi cho AI hơn cho lập trình viên web app rất nhiều. Nhìn vào MCP (giao thức điều khiển nhập vai) là thấy tool discoverability mạnh đến mức nào. HATEOAS có thể mang lại lợi ích tiềm năng lớn ngay cả cho việc tiêu thụ bare API kiểu này
Liên kết tới tài liệu RESTful service API của Cơ quan Thời tiết Quốc gia Mỹ, kiểu API thông tin công khai được thiết kế tốt như vậy thật sự rất dễ chịu khi dùng
Liên quan đến ý "gánh nặng nhận thức ban đầu khi xây dựng client hypermedia thực thụ quá lớn, nên hardcode URI template (/users/{id}/orders, v.v.) vẫn thấy tiện hơn", tôi đã trực tiếp cảm nhận bằng kinh nghiệm rằng đúng là như vậy sẽ dễ hơn. Các nguyên tắc REST thuần túy có tỷ lệ chi phí/lợi ích kém trong đa số tình huống. Giống như lò vi sóng mà chỉ có một nút để điều khiển menu/cách vận hành/thời gian sẽ phiền hơn rất nhiều so với việc dùng các nút tiêu chuẩn quen thuộc. Cái máy đọc mã lỗi động cơ 2 nút mà tôi đang dùng ngoài đời cũng khó thao tác một cách ngớ ngẩn. Văn hóa vẫn yêu cầu phải đọc luận văn của Fielding cũng là một chuyện gây tranh cãi khá nghiêm trọng. Nếu là ý tưởng tốt thì phải có thể được giải thích dễ hiểu bằng nhiều cách khác nhau, từ góc nhìn đại chúng hơn. Ví dụ, chẳng ai nói muốn hiểu vật lý thì bắt buộc phải đọc Principia của Newton cả
Để việc áp dụng mẫu RESTful/HATEOAS thật sự có giá trị thì cần có client hiểu được nó. htmx: hypermedia clients intercoolerjs: hatoeas-is-for-humans
Các UI designer muốn kiểm soát chi tiết giao diện của màn hình. Có action trên resource cần hiện thành nút lớn, có action nên giấu trong menu hoặc thậm chí không hiện trên UI. Nếu action được render động dựa trên phản hồi API theo từng trạng thái cụ thể, thì mọi action sẽ trông giống nhau. Vì thế tôi cho rằng RESTful API không phù hợp để triển khai UI frontend web thông thường
Lập luận này có nhiều điểm sai
Theo kinh nghiệm của tôi, phát triển "RESTful API" hiếm khi liên quan trực tiếp đến UI. Nếu chỉ cần UI thật sự thì bản thân API là không cần thiết, cứ dùng cách server-driven (kiểu DWR ngày xưa) là được
HATEOAS có vẻ hầu như không được dùng trong thực tế, nên tôi không hiểu tại sao nó vẫn còn được tranh luận nhiều như vậy. Tôi tò mò không biết có nơi nào thật sự dùng nó không, và liệu có tồn tại "client tự động khám phá" nào thực sự không cần biết trước thông tin từ server hay không
Xin nhắc lại là ACME (giao thức của Let’s Encrypt) là HATEOAS-based. Nó trên thực tế được dùng ở hầu hết các dịch vụ HTTPS. Bản thân HTTP cũng vốn là giao thức HATEOAS nếu được dùng đúng cách. "auto-discovery" nghĩa là có thể duyệt resource thông qua link type hoặc những thứ như ‘next’. Tất nhiên client vẫn phải biết trước ý nghĩa của "next". LLM cũng rất mạnh ở kiểu tự động khám phá này
Tôi từng dùng HATEOAS trong một hệ thống giám sát video cấp doanh nghiệp. Nó giải quyết rất tốt vấn đề version/quyền hạn ở cấp API. Cũng dùng kèm nhiều RFC khác. Nhưng vấn đề số một là mọi người thường vì muốn "tiện" mà phá vỡ mô hình, rồi lại tạo ra thêm độ phức tạp. Ngoài ra, JSON về bản chất không phải định dạng hypertext, nên khi cố nhét HATEOAS vào application/json thì cảm giác rất gượng ép
Bạn đang dùng HATEOAS để nhập bình luận, và ngay lúc này cũng đang trả lời bằng nó. "Client tự động khám phá kỳ diệu" xử lý việc đó chính là "web browser"
htmx có lẽ là nỗ lực thực tế nhất
Các chuẩn như OData cũng hầu như chẳng được dùng, mà bản thân nó cũng không thật sự phổ biến. HATEOAS lại càng thiếu độ phổ biến và tiêu chuẩn, nên có vẻ càng khó mở rộng hơn
Điều luôn dễ bị bỏ sót trong tranh luận này là kiểu người tiêu thụ backend API. REST và HATEOAS thường có ý nghĩa hơn khi phía tiêu thụ là bên thứ ba không trực tiếp sở hữu backend. Ví dụ, người tiêu thụ cuối của trang HTML truyền thống là người dùng trình duyệt. MCP gần đây cũng xuất hiện vì cần "discovery và diễn giải" cho nhiều JSON RPC API khác nhau. Ngược lại, khi frontend và backend gắn 1:1 với nhau thì lợi ích của REST không lớn tương xứng với chi phí. Khi đó phải tài liệu hóa/spec theo cách generic hơn, còn trong thực tế thì những công cụ cố tình bỏ qua separation of concerns để tăng năng suất (như trPC) đôi khi lại hữu ích hơn nhiều. Ở giai đoạn prototype thì tích hợp end-to-end sẽ nhanh hơn
Rất đồng ý, và xin giới thiệu các bài HATOEAS is for humans htmx: hypermedia clients
*HATEOAS
Trước lập luận rằng có thể tạo client khám phá động bằng HATEOAS và schema reference (XSD, JSON Schema, v.v.), thì trên thực tế các tính năng như "additionalProperties" của JSON schema lại lặp lại đúng vấn đề gốc. Tôi cho rằng cung cấp tài liệu theo kiểu "out of band" còn vững chắc hơn. Vậy nếu chỉ đưa một link tới tài liệu Swagger trong "_links", rồi để client tự xử lý thông tin về self path thì sao? Nếu vậy thì tại sao "_links" phải tồn tại? Nếu đã có client xử lý được kiểu tài liệu JSON phức tạp như vậy thì dùng Swagger template, v.v. lại còn có mật độ thông tin và tính động cao hơn nhiều. Chỉ với các CRUD link thì không đủ để mô tả toàn bộ API đúng nghĩa, mà dùng JSON schema để bao phủ mọi thứ cũng là bất khả thi
Cứ gọi nó là HTTP API thì mọi người sẽ đều vui vẻ hơn. Bản thân REST ban đầu vốn không được thiết kế cho API. Ngay từ xuất phát điểm, REST là để phục vụ hệ thống thông tin cho con người nhận và sử dụng, chứ không phải cho chương trình