Tôi có nên sử dụng WADL để mô tả API RESTful của mình không?

Tôi sắp bắt tay vào một dự án sử dụng rộng rãi cách tiếp cận RESTful đúng cách. Đó là, nó sử dụng HATEOAS và phục vụ các tài nguyên theo cách cho phép khách hàng khám phá chung.

Tôi muốn đảm bảo rằng tôi cung cấp một mô tả về các điểm cuối của mình theo cách cho phép các ứng dụng khách được tạo tự động bằng nhiều ngôn ngữ. Tôi hiểu rằng đối với các dịch vụ web dựa trên SOAP tôi có thể sử dụng WSDL và rõ ràng có WSDL2 cung cấp định nghĩa lớn hơn về các động từ HTTP được sử dụng với REST. Tuy nhiên tôi thấy nhiều bài viết lắc lư qua lại về tiện ích của nó.

Vì vậy, tôi có nên sử dụng WADL để cho phép các trình tạo mã bên ngoài nhanh chóng xây dựng ứng dụng khách cho ứng dụng web của mình không hoặc có tiêu chuẩn nào tốt hơn được mong đợi không?

Lời khuyên của tôi là đừng bận tâm. WADL chưa được áp dụng rộng rãi Xem câu hỏi này trên Stack Overflow và có một số quan điểm mạnh mẽ rằng nó không phù hợp với loại REST 'đúng' mà bạn mô tả, như được hiển thị ở đây trong một câu hỏi về Stack Overflow khác .

Các mô tả WADL tốn nhiều thời gian để xây dựng (và chủ yếu là thủ công) và chúng thêm một độ giòn mà HATEOAS được thiết kế để tránh - tức là bạn sẽ có một số điểm nhập cảnh được xác định rõ nhưng chính xác cách thức tiến hành của khách hàng của bạn được xác định bởi các liên kết mờ, không được xác định trước 'hợp đồng'.

Điều đó không có nghĩa là bạn nên chạy trốn hoàn toàn khỏi tài liệu, định nghĩa lược đồ, v.v., mặc dù đã kết thúc phổ RESTifarian sẽ đề nghị bạn có thể tiếp cận mức độ tự mô tả cao như vậy mà bạn không cần đến chúng. Tôi đã không tìm thấy điều này là trường hợp trong thực tế. Một vài ví dụ hoạt động vững chắc nên là tất cả những gì một nhà phát triển xa lạ cần. Và tìm ra một vài khách hàng cho API của riêng bạn để dùng thử (đủ dễ dàng từ JQuery). Điều đó sẽ cung cấp cho bạn một dấu hiệu tốt cho dù bạn đang xây dựng một cái gì đó tiêu thụ hay không.

Một nguồn thông tin tốt trong lĩnh vực này là Ngôn ngữ ứng dụng siêu văn bản . Tôi thấy một số trong đó hơi nặng nề, nhưng các cuộc tranh luận trong danh sách gửi thư là tốt và hiện tại và có liên quan.

Hy vọng rằng sẽ giúp bạn bắt đầu.

Trạng thái giao diện REST được điều khiển từ bất kỳ thứ gì khác ngoài trình duyệt tương tác không tốt lắm. HATEOAS là một nguyên tắc tốt, nhưng nó dẫn đến các giao diện hướng đến con người rất mạnh mẽ và nó có xu hướng dẫn đến gánh nặng của giao diện người dùng được đặt lên nhà phát triển dịch vụ (thường khá bận rộn khiến bản thân dịch vụ hoạt động).

Bản thân WADL không quá tuyệt vời; nó không thực sự nắm bắt đủ các ngữ nghĩa của dịch vụ để có thể cải thiện mọi thứ. Tất nhiên, đây là một vấn đề khó khăn nói chung. WSDL hiếm khi tiết lộ đủ thông tin và điều đó đã gây ra nhiều nỗ lực hơn cho vấn đề (có thể đính kèm đủ thông tin, nhưng hầu như không ai thực sự làm như vậy).

Tuy nhiên, người ta nói rằng một đồng nghiệp của tôi đã dành nhiều tháng làm việc trên thư viện sử dụng giao diện REST cho một dịch vụ và giao diện được mô tả WSDL cho cùng một dịch vụ ^[*] được tự động chuyển sang chất lượng gần như tương đương trong vài giây; phần còn lại của con đường là khoảng một ngày viết các lớp gói. Linh cảm của tôi (dựa trên kích thước mẫu hạn chế) là bạn không thể thoát khỏi sự giòn giã trong một dịch vụ phức tạp vì ngữ nghĩa của dịch vụ chắc chắn sẽ phát triển theo thời gian và REST tốt hơn trong việc điều khiển giao diện cho con người trong khi SOAP tốt hơn cho thư viện giao diện (có công cụ máy khách WSDL / SOAP tốt cho hầu hết tất cả các ngôn ngữ lưu ý). Trừ khi bạn có được sự sang trọng khi làm cả hai, việc tập trung vào cái nào sẽ phụ thuộc vào nhóm khách hàng nào bạn quan tâm nhất.

Tôi sẽ không nỗ lực nhiều vào WADL, nhưng nếu khung REST của bạn sẽ tạo ra nó cho bạn (Apache CXF làm điều này) thì không có lý do cụ thể nào để không cung cấp nó. Bất cứ ai muốn loại bỏ mã của bạn sẽ muốn WSDL + SOAP.

^{[*] Là tác giả của dịch vụ được đề cập, tôi có thể chắc chắn rằng cả hai giao diện đều hỗ trợ các hoạt động giống nhau - có một mô hình trừu tượng cơ bản phổ biến - và theo kiểu tự nhiên, đối với cả hai loại giao diện. Về mặt dịch vụ, chắc chắn có một số điều dễ dàng hơn với REST và những thứ khác với SOAP.}

Các W3C đã làm cho một đề nghị chính thức cho một tiêu chuẩn tài liệu REST của dựa trên WSDL 2.0 . Đây là một trích dẫn từ bài viết của IBM :

Thuật ngữ Dịch vụ web thường được liên kết với các dịch vụ dựa trên hoạt động hoặc hành động bằng cách sử dụng các tiêu chuẩn SOAP và WS *, chẳng hạn như Địa chỉ WS và Bảo mật WS. Thuật ngữ dịch vụ Web REST thường dùng để chỉ kiến ​​trúc dịch vụ Web dựa trên tài nguyên sử dụng HTTP và XML. Mỗi kiểu dịch vụ Web kiến ​​trúc này đều có vị trí của nó, nhưng cho đến gần đây, tiêu chuẩn WSDL không hỗ trợ cả hai kiểu. Liên kết HTTP WSDL 1.1 không đủ để mô tả giao tiếp với HTTP và XML, do đó không có cách nào để mô tả chính thức các dịch vụ Web REST với WSDL. Ấn bản của WSDL 2.0, được thiết kế dành cho các dịch vụ Web REST, như một khuyến nghị của World Wide Web Consortium (W3C) có nghĩa là bây giờ có một ngôn ngữ để mô tả các dịch vụ Web REST.