REST API：單個 API 是否應該承擔多項職責？

Question

我們有分類商品網站，我們沒有登錄但用戶可以查看其他用戶列出的產品。 要查看其他用戶的詳細信息，他們必須提供他們的聯系方式。 為了驗證用戶是否提供了正確的手機號碼，我們將 OTP 代碼發送回該號碼。 API 流程如下所示：

1. //當用戶填寫表單以獲取特定股票的賣家詳細信息時將點擊 API（這需要“stockId”和“mobile”作為輸入）：

POST /api/lead/

{
  "stockId": 123,
  "mobile": 9890384328
}

如果已驗證“移動”，則 API 的響應（響應代碼：200）：

{
  "sellerName": "xyz",
  "sellerMobile": "+123232312",
  "sellerAddress": "21, park street, new york"
}

如果“移動”尚未驗證，則響應（響應代碼：403）：

{
   "OTP verification required. OTP is sent to the mobile number."
}

2. 用戶使用在移動設備上收到的 OTP 再次向同一個潛在客戶 API 發送回請求：

請求有效載荷：

{
  "stockId": 123,
  "mobile": 9890384328,
  "otp": 1234
}

如果 OTP 正確，它會發回賣家詳細信息作為響應。 如果提供的 OTP 不正確，則響應為：

{
  "Incorrect OTP."
}

我在這個 API 設計中看到了幾個問題：

1. 這個 API 做了很多工作，即返回賣家詳細信息、返回 OTP、驗證 OTP 等。我們可以輕松地將 OTP 相關功能分解為其他一些 API。 例如，一個用於生成 OTP 的 API，即 GET /api/otp/，另一個用於驗證 OTP 的 API，即 POST api/verifyotp/。 這會增加來自客戶端的 API 調用次數，即第一個客戶端將啟動 POST 引導 API，如果未驗證數量，客戶端將命中 OTP API。 要通過 OTP 進行驗證，它將調用 verifyOTP api。 如果通過驗證，它將調用 Lead API 以獲取賣家詳細信息。 因此，基本上它在上述方法中進行了 4 個 API 調用與 2 個 API 調用。
2. 這與 HATEOS 不兼容，HATEOS 建議“REST 客戶端通過簡單的固定 URL 進入 REST 應用程序。客戶端可能采取的所有未來操作都在從服務器返回的資源表示中發現。”

有人可以建議哪種方法更好嗎？

Answer 1

簡單的回答：沒有。

它被稱為單一責任原則是有原因的。

在您的公共 API 中允許多個責任意味着 API“端點”必須了解不同的責任，以便“分派”這些方面中的每一個的“正確”實現。 或者您允許您的雙重職責 API 設計通過提供該實現的單一事物來破壞您的實現。

除此之外：當你有不同的職責時，OK/error 返回碼的范圍會變得更加復雜。 這只會讓“一切”變得更加困難。 為您編寫測試 - 也為使用您的 API 的客戶編寫測試。

在您的情況下，用戶執行以下操作：

• 首先使用 /api/lead
• 被告知“未驗證”
• 使用OTP生成API獲取驗證碼
• 然后使用特定的OTP API提交驗證碼
• 然后再次使用 /api/lead