Cấu trúc tài liệu trực tuyến cho API REST

Tôi đang xây dựng API Rest đầu tiên của mình để tuần tự hóa dữ liệu sang các định dạng JSON và XML. Tôi muốn cung cấp một trang chỉ mục cho các ứng dụng khách API, nơi họ có thể chọn các điểm cuối được triển khai.

Tôi cần bao gồm thông tin gì để làm cho API của mình hữu ích nhất và tôi nên tổ chức nó như thế nào?

Đó là một câu hỏi rất phức tạp cho một câu trả lời đơn giản.

Bạn có thể muốn xem các khung API hiện có, như Đặc tả Swagger ( OpenAPI ) và các dịch vụ như ap ủy.io và apiblueprint.org .

Ngoài ra, đây là một ví dụ về cùng một API REST được mô tả, tổ chức và thậm chí được tạo kiểu theo ba cách khác nhau. Nó có thể là một khởi đầu tốt để bạn học hỏi từ những cách phổ biến hiện có.

• https://api.coinsecure.in/v1
• https://api.coinsecure.in/v1/originalUI
• https://api.coinsecure.in/v1/slateUI#!/Blockchain_Tools/v1_bitcoin_search_txid

Ở cấp cao nhất, tôi nghĩ rằng tài liệu API REST chất lượng ít nhất yêu cầu những điều sau:

• danh sách tất cả các điểm cuối API của bạn (URL cơ sở / tương đối)
• loại phương thức HTTP GET / POST / ... tương ứng cho mỗi điểm cuối
• Yêu cầu / phản hồi kiểu MIME (cách mã hóa các tham số và phân tích cú pháp trả lời)
• một yêu cầu / phản hồi mẫu, bao gồm tiêu đề HTTP
• loại và định dạng được chỉ định cho tất cả các tham số, bao gồm cả những tham số trong URL, nội dung và tiêu đề
• một mô tả văn bản ngắn gọn và các ghi chú quan trọng
• một đoạn mã ngắn cho thấy việc sử dụng điểm cuối trong các ngôn ngữ lập trình web phổ biến

Ngoài ra, có rất nhiều khung tài liệu dựa trên JSON / XML có thể phân tích cú pháp định nghĩa hoặc lược đồ API của bạn và tạo ra một bộ tài liệu thuận tiện cho bạn. Nhưng sự lựa chọn cho một hệ thống tạo tài liệu phụ thuộc vào dự án, ngôn ngữ, môi trường phát triển và nhiều thứ khác của bạn.