如何設計和記錄非 REST Web API？

Question

我需要設計一個 Web API，它不是 REST。 它會像這樣工作：

第 3 方網站（后稱為“消費者”）應該使用 JSON 負載對我的服務進行 POST 調用。 調用應由 Web 瀏覽器執行。 我的服務將處理請求並顯示一些 UI，可能會引導最終用戶完成一系列表單/頁面並收集輸入。 最后，我的服務將通過對“消費者”指定的回調 URL 進行 POST 調用，將結果和控制返回給“消費者”。

使用的技術將是 Spring Boot。 我的問題：

• 這種 API/集成有什么官方名稱嗎？
• 是否有一些智能（自動）方式來記錄此類 API？ 尤其是用作輸入和輸出的 JSON 有效負載。 我嘗試使用 Swagger，但它似乎不能很好地服務於這個用例。 也許是 JSON 模式？ 我以前沒有用過，乍一看它看起來有點被遺棄，更多地是為了驗證。

Answer 1

對於您的第一個問題，我想您可以將其稱為“HTTP API”，因為您正在利用 HTTP 協議，而不必遵守 REST 約束。 我基於以下參考。

關於您的文檔，您可以使用Slate 之類的東西，這是一個基於降價的 API 文檔生成器。

Answer 2

我的服務將處理請求並顯示一些 UI，可能會引導最終用戶完成一系列表單/頁面並收集輸入。

如果我理解正確，那么您正在使用 HTML 響應 POST 請求（“顯示一些 UI”、“表單/頁面”）。 我根本不會稱其為 API，我什至可能不會使用“服務”這個詞。 我會說你正在設計的只是一個網絡應用程序。

要將其轉換為實際服務，您需要將其分開，以便 UI 部分在其他地方處理，並且您的服務僅返回data 。 由於您在請求負載中接受 JSON，因此響應負載的最自然格式也是 JSON。

如果您的服務絕對有必要將用戶重定向到一個網頁，在那里他們可以提供附加信息以繼續初始 POST 請求開始的任何進程，則返回該頁面的 URL。 讓 URL 包含 Web 應用程序 UI 生成表單所需的任何查詢參數。

（我假設這本質上是動態的，因為否則您只需預先指定它並接收初始 POST 的請求負載中的所有數據。）

更簡潔的方法是讓消費者處理所有 UI 問題，並且只讓您的服務告訴消費者它可以/必須在后續調用中提供哪些附加信息。 這將給消費者更多的自由，因為它允許他們從任何類型的應用程序（命令行、移動應用程序、網絡等）使用您的 API。