REST设计-多端点

Question

我目前正在为分配编写REST规范。

这个问题涉及路由以及如何设计资源和端点。

资源最好有以下多个端点：

Method | Resource              | Description
-------+-----------------------+-------------------------
POST   | /cash-card/create     | Create a prepaid account
POST   | /cash-card/:id/pay    | Pay some service
PUT    | /cash-card/:id/topup  | Top up cash card
DELETE | /cash-card/:id/delete | Delete prepaid Account

或者有一个端点并使用如下的HTTP方法进行区分：

Method | Resource       | Description
-------+----------------+-------------------------
POST   | /cash-card/    | Create a prepaid account
POST   | /cash-card/:id | Pay some service
PUT    | /cash-card/:id | Top up cash card
DELETE | /cash-card/:id | Delete prepaid Account

在这两个版本中，我都使用路径参数来标识资源。

这只是设计上的选择吗？

还是有关于如何设计资源的约定？

谢谢，我很感谢你的帮助。

Answer 1

这只是设计上的选择吗？

不，你做的是真正的权衡。

HTTP是一种应用程序协议，其应用程序域是通过网络(韦伯，2011年)传输文档。GET、POST、PUT、PATCH、DELETE都是具有文档存储语义的请求：“使用此键查找文档，并对其进行处理”。

因此，您的"REST“是一个外观，目的是使您的域应用程序协议看起来像一个哑文档存储。

这样做的好处是，您可以利用已经完成的大量工作来生成通用组件(浏览器、缓存、索引蜘蛛等)。

这项工作的一个例子是缓存失效；通用组件知道，对POST /cash-card/:id的成功响应会使缓存中的表示无效(想必是在GET /cash-card/:id之后)。

当我们代替POST /cash-card/:id/pay时，我们不会得到免费的无效声明，因为通用客户端并不认为/cash-card/:id/pay和/cash-card/:id之间有任何关系。标识符在语义上是不透明的。

这意味着，如果我们有一个资源(/foo)可能被修改了几种不同的方式(不同的领域语义)，它们都可能看起来像POST /foo。然后，在服务器上，我们需要检查HTTP请求，以发现域语义的其余部分。

如果您想象在网络上这样做，您可能有一个/cash-card/:id资源，然后有一堆表单用于构造其他有趣的消息；/cash-card/:id/pay用于表单支付，/cash-card/:id/topup用于表单将更多的钱放在卡片上，等等。所有这些表单都会向/cash-card/:id提交它们的请求，因为如果更改成功的话，这就是您想要无效的资源。

与“通用缓存”相比，更喜欢“不缓存”或“自定义缓存”在某些情况下是完全有效的。好的属性伴随着遵从约束的成本；您需要计算的是属性和约束的哪个组合将提供最佳的利润。