REST API:一个人 API 应该承担多项责任吗?
REST API: Should single API have multiple responsibilities?
我们有分类商品网站,我们没有登录但用户可以查看其他用户列出的产品。要查看其他用户的详细信息,他们必须提供他们的联系方式。为了验证用户是否提供了正确的手机号码,我们将 OTP 代码发送回该号码。 API 流程如下所示:
- //API 当用户填写表格以获取特定库存的卖家详细信息时被点击(这需要“stockId”和“mobile”作为输入):
POST /api/lead/
{
"stockId": 123,
"mobile": 9890384328
}
如果“移动”已经验证(响应代码:200),API 的响应:
{
"sellerName": "xyz",
"sellerMobile": "+123232312",
"sellerAddress": "21, park street, new york"
}
“移动”尚未验证时的响应(响应代码:403):
{
"OTP verification required. OTP is sent to the mobile number."
}
- 用户使用在移动设备上收到的 OTP 再次向同一个潜在客户发回请求 API:
请求负载:
{
"stockId": 123,
"mobile": 9890384328,
"otp": 1234
}
如果 OTP 正确,它会发回卖家详细信息作为响应。如果一次性密码
提供不正确,响应是:
{
"Incorrect OTP."
}
我在这个 API 设计中发现了一些问题:
- 这个 API 正在做很多工作,即返回卖家详细信息、返回 OTP、验证 OTP 等。我们可以轻松地将 OTP 相关功能分解为其他 API。例如,一个 API 用于生成 OTP,即 GET /api/otp/,另一个 API 用于验证 OTP,即 POST api/verifyotp/。这将增加来自客户端的 API 调用次数,即第一个客户端将启动 POST 引导 API,如果未验证号码,客户端将命中 OTP API。要通过 OTP 验证,它将调用 verifyOTP api。如果得到验证,它将调用潜在客户 API 以获取卖家详细信息。因此,基本上它在上述方法中进行了 4 API 次调用与 2 次 API 次调用。
- 这不是对 HATEOS 的抱怨,它建议“REST 客户端通过简单的固定 URL 进入 REST 应用程序。客户端可能采取的所有未来操作都在从服务器返回的资源表示中发现。”
有人可以建议哪种方法更好吗?
简单回答:否。
它被称为单一责任原则是有原因的。
允许在 public API 中承担多项责任意味着 API "endpoint" 必须了解 "dispatch" 的不同责任每个方面的 "correct" 实现。或者,您允许双重责任 API 设计 破坏 您的实现,方法是让一个东西提供该实现。
除此之外:当您承担不同的职责时,OK/error return 代码的范围就会变得更加复杂。这只会让 "everything" 更难。为您编写测试 - 也为使用您的 API 的客户。
在你的例子中,用户做了:
- 先使用/api/lead
- 被告知 "not verified"
- 使用OTP生成API获取验证码
- 然后使用特定的 OTP API 提交验证码
- 然后再次使用 /api/lead
我们有分类商品网站,我们没有登录但用户可以查看其他用户列出的产品。要查看其他用户的详细信息,他们必须提供他们的联系方式。为了验证用户是否提供了正确的手机号码,我们将 OTP 代码发送回该号码。 API 流程如下所示:
- //API 当用户填写表格以获取特定库存的卖家详细信息时被点击(这需要“stockId”和“mobile”作为输入):
POST /api/lead/
{
"stockId": 123,
"mobile": 9890384328
}
如果“移动”已经验证(响应代码:200),API 的响应:
{
"sellerName": "xyz",
"sellerMobile": "+123232312",
"sellerAddress": "21, park street, new york"
}
“移动”尚未验证时的响应(响应代码:403):
{
"OTP verification required. OTP is sent to the mobile number."
}
- 用户使用在移动设备上收到的 OTP 再次向同一个潜在客户发回请求 API:
请求负载:
{
"stockId": 123,
"mobile": 9890384328,
"otp": 1234
}
如果 OTP 正确,它会发回卖家详细信息作为响应。如果一次性密码 提供不正确,响应是:
{
"Incorrect OTP."
}
我在这个 API 设计中发现了一些问题:
- 这个 API 正在做很多工作,即返回卖家详细信息、返回 OTP、验证 OTP 等。我们可以轻松地将 OTP 相关功能分解为其他 API。例如,一个 API 用于生成 OTP,即 GET /api/otp/,另一个 API 用于验证 OTP,即 POST api/verifyotp/。这将增加来自客户端的 API 调用次数,即第一个客户端将启动 POST 引导 API,如果未验证号码,客户端将命中 OTP API。要通过 OTP 验证,它将调用 verifyOTP api。如果得到验证,它将调用潜在客户 API 以获取卖家详细信息。因此,基本上它在上述方法中进行了 4 API 次调用与 2 次 API 次调用。
- 这不是对 HATEOS 的抱怨,它建议“REST 客户端通过简单的固定 URL 进入 REST 应用程序。客户端可能采取的所有未来操作都在从服务器返回的资源表示中发现。”
有人可以建议哪种方法更好吗?
简单回答:否。
它被称为单一责任原则是有原因的。
允许在 public API 中承担多项责任意味着 API "endpoint" 必须了解 "dispatch" 的不同责任每个方面的 "correct" 实现。或者,您允许双重责任 API 设计 破坏 您的实现,方法是让一个东西提供该实现。
除此之外:当您承担不同的职责时,OK/error return 代码的范围就会变得更加复杂。这只会让 "everything" 更难。为您编写测试 - 也为使用您的 API 的客户。
在你的例子中,用户做了:
- 先使用/api/lead
- 被告知 "not verified"
- 使用OTP生成API获取验证码
- 然后使用特定的 OTP API 提交验证码
- 然后再次使用 /api/lead