我正在寻找有关处理付款的API设计的建议。 API公开了一种资源类型,名为“payment”。
调用者(通常是另一个后端)可以
PUT /payments/{id}
为了启动付款(可以在不同阶段成功或失败,现在和以后)。
如果请求格式错误(缺少必填字段,数字太少的信用卡号等),我们会发送400 bad request
并退出此处。
假设请求格式正确,PUT
请求的业务逻辑会同步触发进一步的操作,在某些情况下,根据付款方式(信用卡,PayPal等),可能会导致付款被立即拒绝。呼叫者应该不知道细节,他们的观点只有三个相关的结果:
我们已经知道付款被拒收(例如,因为信用卡网络拒绝了金额)。应将最终用户(浏览器)重定向到错误页面。
为了继续,最终用户需要被重定向到第三方页面,例如PayPal结账页面,以确认付款。
客户现在可以继续订购流程,无需进一步的用户交互。应将最终用户(浏览器)重定向到成功页面。 (这通常不是一个真正的“成功”,它只是一个“没有错误”。稍后,我们将尝试收集实际的钱,例如通过收取信用卡;这可能会失败或成功,并且最终我们将异步通知调用者;但是现在一切都很好。)
始终创建接收PUT
的URL的资源非常重要,无论是否立即识别付款失败,以便调用者可以发布后续的
GET /payments/{id}
并将返回包含各种信息的付款表示,最重要的是状态:
{
"payment-method": "...",
"amount": ...,
...
"status": "OPEN"
}
问题:
编辑:潜在答案
有两个可能的答案,两者都有优点。基本上我想知道的是,如果付款被拒,我们是否应该退回2xx或4xx。
可能的答案1:如果付款遭拒,这是一个错误,服务应返回4xx,例如409 conflict
,表示付款未成功。其他两种情况应该返回3xx(重定向)或201 created
。这使得调用者可以根据状态代码轻松决定如何继续。
潜在答案2:在所有三种情况下,payment
资源都已创建,之后可通过GET
获取。因此,API应该始终表示这是成功的,例如,作为201 created
或202 accepted
。此外,应该重定向的不是调用者(=后端服务),而是最终用户的浏览器;在重定向目标中找不到payment
资源;因此案例2也不应返回3xx。只有当客户端在语法上混淆了调用等时才应返回4xx
。客户端代码应该根据HTTP状态决定如何继续,但是基于status
字段有效载荷。
哪个更合适?