Tài liệu về giao diện REST với sơ đồ

Có ai có đề xuất về việc tạo một biểu đồ sơ đồ của giao diện web kiểu REST không? Để cung cấp tài liệu kỹ lưỡng cho các nhà đồng phát triển, tôi đã chơi đùa trong việc mô hình hóa giao diện để sửa đổi và tạo tài nguyên sản phẩm:

Hệ thống cụ thể này bắt đầu hoạt động khác với số lượng tài nguyên / xác thực người dùng, vì vậy trước khi tôi sửa đổi, tôi đang tìm kiếm một số giải thích:

Độ phức tạp: làm thế nào bạn có thể đơn giản hóa cấu trúc tổng thể để làm cho nó dễ đọc hơn?
Biểu tượng hiển thị: điều này có thích hợp để đại diện cho một trang không?
Biểu tượng thao tác thủ công: điều này có thích hợp để thể hiện hành động của người dùng như nhấp chuột không?

Bất kỳ đề xuất khác sẽ được đánh giá rất cao.

Tôi xin lỗi vì đã đăng lại. Trang web stackexchange chính cho thấy câu hỏi này được trình bày tốt hơn trên các lập trình viên.

documentation rest flowchart

— James Kassemi
nguồn

Câu trả lời:

Tôi cảm thấy Biểu đồ trình tự / Biểu đồ trình tự thư phù hợp hơn để ghi lại tương tác API RESTful. Những gì bạn có là một sơ đồ trạng thái, trong khi định nghĩa API RESTful là không trạng thái.

nhập mô tả hình ảnh ở đây

— vartec
nguồn

Máy chủ trong kiến trúc RESTful là không trạng thái, tuy nhiên, bản thân hệ thống thì không. Trạng thái được lưu trữ tại máy khách và các chuyển đổi trạng thái có thể được mã hóa trong phạm vi đại diện của tài nguyên để máy khách có thể bắt đầu chuyển đổi sang trạng thái mới bằng cách gửi yêu cầu đến máy chủ. Tôi nghĩ rằng một sơ đồ trạng thái khá hiệu quả trong việc truyền đạt trạng thái hệ thống tổng thể, ngay cả khi nó không ghi lại chính xác các yêu cầu và phản hồi giữa các thành phần máy khách và máy chủ.

— Adam Jaskiewicz

@Adam: bạn nói đúng về hệ thống tổng thể. Nhưng câu hỏi hỏi rõ ràng về tài liệu giao diện REST, không phải toàn bộ hệ thống.

— vartec

Cảm ơn, vartec, MSC tài liệu hiệu quả giao diện REST trong trường hợp này. Tôi vẫn tò mò muốn nghe những cải tiến đối với tài liệu của mô hình này về trạng thái của khách hàng.

— James Kassemi

Các hệ thống RESTful thực hiện ràng buộc siêu văn bản khiến máy khách hoạt động như một máy trạng thái. Tôi đã tìm thấy bằng cách sử dụng sơ đồ loại máy trạng thái là một công cụ hiệu quả hơn nhiều để ghi lại các tương tác máy khách / máy chủ RESTful.

— Darrel Miller

Có thể mô tả if-s và while-s trong sơ đồ này không?

— hellboy

Tôi chắc chắn nghĩ rằng một máy trạng thái là cách phù hợp để ghi lại các tương tác của hệ thống RESTful. Tuy nhiên, tôi vẫn đang làm việc đúng cách để thể hiện các yếu tố hypermedia trong sơ đồ. Dưới đây là một vài sơ đồ thử nghiệm mà tôi đã thực hiện.

mê cung

nhập mô tả hình ảnh ở đây

— Darrel Miller
nguồn

Hai đồng xu của tôi về chủ đề này, vì tôi đang làm việc với điều này vào lúc này:

tập trung vào các nguồn lực và quan hệ của họ
- và không phải trên hành động, và do đó phương thức HTTP
- khi bạn theo một liên kết, bất kể bạn đã thực hiện GET hay POST, các trạng thái có thể tiếp theo của bạn được quyết định chủ yếu bởi tài nguyên hiện tại và ít hơn nhiều bởi phương thức HTTP của yêu cầu

Với ý nghĩ đó:

xóa một số liên kết rõ ràng (nghĩa là tự, để root)
xóa nhãn của các mối quan hệ nếu nó chỉ nói "chiếc xe này có [chủ sở hữu]", trong đó tài nguyên nguồn là xe hơi và tài nguyên đích là chủ sở hữu. Nó không thêm bất cứ điều gì
một biểu đồ tương tác có thể giúp ích rất nhiều với sơ đồ trạng thái phức tạp ( ví dụ )

— Andrei Neculau
nguồn