对同一 URI 执行多个操作时的 RESTful API

Question

据我所知，RESTful API 使用了四种方法:

GET 用于获取资源。
POST 用于更新资源。
PUT 用于创建或替换资源。
DELETE 用于删除资源。

假设我们有一个名为 apple 的资源，我们可以通过多种方式“更新”它。例如，削皮、切片或制成苹果汁。
这三种不同的更新操作均采用不同的参数，并且它们的 API 的共同部分是:

POST /apple HTTP/1.1
Host: www.example.com

<different combination of arguments>

在这种情况下，三个 API 共享相同的 URI 和相同的请求方法，唯一的区别是参数。我认为这迫使后端准备好接受这些参数的联合集，并且为了区分实际请求的操作，后端需要检查参数的组合。这太复杂了，而且不优雅。

所以我的问题是:
在这个苹果案例中，如何设计出一套优雅的 RESTful API，使后端能够轻松处理它。

Answer 1

首先，尽量避免将 HTTP 方法与 CRUD 操作混为一谈。我相信这是 REST 中困惑的主要根源。 HTTP 方法不会像这样干净地转换为 CRUD 操作。我这里有详细的答案:

S3 REST API and POST method

简而言之。

• POST 是用于任何未通过 HTTP 标准化的操作的方法，并使负载服从目标 URI。
• PUT 用于完全替换当前 URI 处的资源，并使负载服从于服务本身。
• PATCH 用于部分幂等更新，当前状态与所需状态之间存在差异。
• DELETE 用于删除资源。
• GET 用于检索资源。

现在，在后端，尝试将 REST 资源想象成一个状态机，您可以在其中使用方法来强制转换，而不是使用方法的对象。这样，您就可以将实现重点放在资源本身上，而不是与协议(protocol)的交互上。例如，您可以直接从方法的有效负载中更改对象的属性，然后调用一个方法来检测需要什么转换。

例如，您可能认为苹果具有三种状态:完整的、削皮的、切片的和榨汁的。您可以使用方法的标准化行为在状态之间进行转换。

例如:

GET /apple 

{"state": "whole",
 "self": "/apple"}

然后你想切片它。你可以这样做:

PUT /apple

{"state": "sliced"}

或者你可以这样做:

PATCH /apple

{"from_state": "whole", "to_state": "sliced"}

或者甚至类似:

POST /apple

{"transition": "slice"}

这个想法是，实现可以足够通用，您不必太担心资源与 HTTP 方法的耦合。

• PUT 版本是幂等的，因此您的客户可以在需要幂等时选择使用它。
• PATCH 版本保证客户端了解当前状态并尝试有效的转换。
• POST版本是最灵活的，你可以做任何你想做的事情，但需要详细记录。您不能简单地假设您的客户知道该方法是如何工作的。

只要您的资源实现了解当 apple.state 更改为其他内容时，它应该检测发生的更改并执行适当的转换，您就与协议(protocol)完全解耦了。使用什么方法并不重要。

我相信这是最优雅的解决方案，并且使后端的所有事情都更容易处理。您可以实现您的对象，而不必过多担心协议(protocol)。只要对象可以在状态之间转换，它们就可以被任何可以影响这些转换的协议(protocol)使用。