Tôi có nên mô tả các dịch vụ REST ở định dạng máy có thể đọc được không?

Question

Hầu hết các giao diện REST tôi thấy được mô tả bằng một trang web đơn giản mô tả URL, phương thức, đầu vào được chấp nhận và kết quả trả về. Ví dụ: Amazon S3 hoặc tài liệu Twitter API.

Nhưng tại sao tôi nên giải quyết với những gì dường như đủ tốt cho Amazon hoặc Twitter ... Vậy, có đáng để mô tả một API REST ở định dạng có thể đọc được trên máy không? Và nếu có, cái nào?

Xác nhận quyền sở hữu WSDL 2.0 là capable of describing REST. WADL được tạo ra một cách rõ ràng để mô tả các dịch vụ REST. Cả WSDL 2.0 và WADL dường như có một bản cập nhật khá nhỏ và dường như nó có ít sự trở lại cho nỗ lực tạo và duy trì tài liệu mô tả. Uestion của tôi về cơ bản là xác nhận hoặc phủ nhận giả định của tôi.

Bạn có sử dụng WSDL/WADL để mô tả các dịch vụ của bạn không? Bạn có dựa vào WSDL/WADL để tiêu thụ các dịch vụ của người khác không? Công cụ lựa chọn của bạn có hỗ trợ một trong hai công cụ này vào lúc này không?

Answer 1

Sau đây chỉ là ý kiến ​​cá nhân của tôi:

Tôi nghĩ WADL tương tự như bản đồ trang cho các trang html. Sơ đồ trang web được coi là một thực hành tốt về mặt lý thuyết, nhưng hiếm khi được thực hiện và thậm chí hiếm khi được mọi người sử dụng.

Tôi nghĩ lý do rất đơn giản - lang thang xung quanh một trang web và đẩy các nút được đặt chiến lược thường đáng giá hơn việc duyệt qua một bản đồ phức tạp.

Phương pháp API REST không được yêu cầu mô tả chính thức. Vì vậy, nếu API được tạo ra một cách chu đáo thì thật dễ dàng để khám phá tất cả các tài nguyên chỉ bằng cách theo các liên kết uri được đặt chiến lược của một tài nguyên RESTful 'home'.

Answer 2

Lợi ích của định nghĩa REST API của máy có thể đọc được là gì?

Điểm REST là dành cho API tương đối đơn giản và dễ hiểu. Ngôn ngữ tự nhiên hoạt động tốt cho việc này.

Nếu bạn muốn nói "Định nghĩa loại API" khi bạn nói "Định nghĩa API" thì có thể có một số giá trị trong việc cung cấp siêu dữ liệu. Tuy nhiên, điều này chỉ là một phần của định nghĩa API.

API "có thể đọc được máy" có thể dễ dàng lặp lại mã nguồn API, vi phạm nguyên tắc DRY.

Việc viết mô tả bằng tiếng Anh về động từ REST và những gì của URI thường đơn giản hơn. Gửi loại được sắp xếp thông qua JSON (hoặc YAML hoặc JAXB) dưới dạng mã nguồn. Đó là API hoàn hảo có thể đọc được bằng máy tính - nguồn làm việc thực tế cho lớp đối tượng tin nhắn.

Answer 3

Có gà/trứng phenonenon ở đây. WADL là vô ích nếu không có công cụ sản xuất hoặc tiêu thụ nó. Các công cụ này là vô ích trừ khi các trang web xuất bản WADL. v.v.

Đối với tôi, Mô hình Amazon hoạt động tốt. Tùy thuộc vào khán giả của bạn, bạn sẽ nhận được nhiều lợi nhuận hơn trong nỗ lực sản xuất mẫu, bao gồm hộp thoại mẫu snips (ví dụ như request1 trên dây, tương tự cho phản hồi 1, sau đó yêu cầu 2, phản hồi 2, v.v.) và mã trong v.v. các ngôn ngữ quan trọng đối với bạn. Nếu bạn muốn đi đến một định nghĩa có thể đọc được máy, bạn có thể sử dụng XSD nếu nó là một định dạng tin nhắn XML. Rõ ràng đây không phải là WADL nhưng kết hợp với mô tả tiếng Anh của bạn, nó có thể cung cấp thêm một chút tiện ích cho các nhà phát triển.

Answer 4

Có, bạn nên làm như vậy.Bạn sẽ có thể tạo mã máy khách, kiểm tra và tài liệu của bạn bằng cách sử dụng một bộ công cụ hỗ trợ WADL. Một số ví dụ có thể được tìm thấy here. Ngoài ra, tôi nghĩ bạn nên gắn bó với WADL, thay vì WSDL 2.0 vì nó ít tiết và đơn giản hơn (IMHO). Trong thực tế, trong WADL bạn mô tả chính xác những gì người dùng nhìn thấy trên trang tài liệu, chỉ cần sử dụng cú pháp XML WADL. BTW, đó là lý do tại sao nó dễ dàng để viết các trình tạo tài liệu dựa trên XSLT cho WADL.

Answer 5

Cách sử dụng phổ biến nhất của WSDL (và WADL theo cùng một cách) là tạo mã. Nó chắc chắn giúp tăng tốc độ phát triển, nhưng không có gì có thể thay thế tài liệu cũ đồng bằng. Đối với con người và không cho máy móc.