端点设计的 RESTful API 最佳实践

Question

假设我想实现两个函数：

1. 注册课程
2. 支付课程费用

我知道我可能有两个像这样的 RESTful API 端点

1. 为学生注册课程： 发送 POST 请求到/myapp/api/students/{id}/courses 请求正文类似

   { "course_id"： 26， "is_discount"：对， "reg_date"："2020-04-23T18：25：43.511Z" }

2. 创建学生的课程付款记录： 发送 POST 请求到/myapp/api/payment-records 请求正文类似

   { "student_id"：204， "course_id"： 26， "金额"：500 }

我的问题是，如何通过仅调用一个 RESTful 端点而不像上面那样将它们分成两个，从而在客户端的一个操作(或一个事务中(完成此操作？因为如果由于卡系统的网络故障而未能成功付款，那么学生注册的课程应相应地回滚。

或者，我应该这样做吗： 发送 POST 请求至/myapp/api/course-registration 像这样的请求正文？

{
course:  {
"course_id": 26,
"is_discount": true,
"reg_date": "2020-04-23T18:25:43.511Z"
},
payment: {
"record_id": 1,
"student_id": 204,
"course_id": 26,
"amount": 500
}
}

Answer 1

我的问题是，如何通过调用一个 RESTful 端点而不像上面那样将它们分成两个，在客户端的一个操作(或一个事务中(完成此操作？

你会如何在网络上做到这一点？

你会有一个带有表单的网页，用于从学生那里收集您需要的所有信息 - 某些字段可能是预先填写的，其他字段可能是"隐藏"的，因此它们不是演示文稿的一部分。 提交表单时，浏览器会将所有这些信息收集到单个application/x-www-form-urlencoded文档中，并将该文档包含在 POST 请求中，该请求针对表单指定的任何 URI。

请注意，您可能还有两个较小的表单 - 可能是同一网页的一部分，也许是其他地方，可以分别进行注册和付款。

关于目标 URI 需要注意的两件事。 浏览器不关心目标 uri 的拼写是什么;它只是将这些信息复制到HTTP请求中。 但是浏览器确实关心目标 URI 是否与其本地缓存中可用的内容相同;请参阅 RFC 7234 中的失效规范。

因此，可用于选择目标的启发式方法是考虑如果 POST 成功，必须刷新哪个缓存文档，并将该文档的标识符用作目标 uri。