在HTTP API中搜索动词

Question

搜索API的最佳实践是什么？

• 使用查询参数进行GET请求，例如：GET /search?q=phone
• 在请求体中使用参数进行GET请求，例如：GET /search {"query": "phone"}
• 在请求体中使用参数进行POST请求，例如：POST /search {"query": "phone"}

- Romper

Answer 1

不要在GET请求中包含正文。这违反了规范：spec：

“GET请求消息中的有效载荷没有定义的语义； 在GET请求上发送有效载荷主体可能会导致一些现有实现拒绝该请求。”

其他两个选项之间存在权衡。 GET请求是可缓存的，安全的和幂等的。它们还大小受限。 POST请求不可靠地缓存，不安全或幂等，并且没有大小限制。还有更多的灵活性 - 你可以稍后在服务器端创建一个过滤资源以返回搜索结果，并且稍后的搜索可以使用该过滤器，可能使用GET，但是如果允许缓存并在创建后更改过滤器定义，请小心。

看着你的具体例子，支持单个“搜索”端点可能很快变得混乱。 如果您尚未考虑其他选项，则建议您考虑其他选项。

- Eric Stein

---

Elasticsearch使用带有请求体的GET方法进行搜索请求。 - Romper

@Romper 当然了。他们抛弃了幂等性和可缓存性，因为他们认为“GET”应该意味着去获取某些东西，“POST”应该意味着去更改某些东西。我不同意他们的决定，而且他们显然违反了规范的书写和意图。规范的作者明确表示，他们的意图是让GET请求体在语义上毫无意义。 - Eric Stein

@Romper 如果有明确的新鲜度信息，响应可能会被缓存。然而，即使规范允许，一些用户代理和中间服务器也不会这样做。 "仅当POST请求包括明确的新鲜度信息时，它们才可被缓存（请参见[RFC7234]的第4.2.1节）。但是，POST缓存并没有得到广泛实现。" [RFC7231 4.3.3]。因此，即使您想要缓存，您也依赖于从客户端到服务边界支持POST缓存的内容。 - Eric Stein

规范并没有说不要在 GET 请求中使用 body。它非常明确地写着不这么说。总的来说，它是这样说的：“我们不为 GET body 定义标准，服务器也不必支持它，因此请谨慎使用。” 大多数主流服务器（如 IIS、Apache 等）在协议级别上都支持 GET body，并且将其处理方式留给代码决定。尽管使用了 body，但仍有许多 GET API 实现不会破坏幂等性或可缓存性。 - Thought

Answer 2

POST请求被认为是在服务器上更改或创建数据的操作。GET被视为“安全方法”，对服务器数据库没有影响。

由于搜索请求通常不会更改任何数据，因此应使用GET请求。限制至少为2000个符号（IE），因此大多数情况下您是相当安全的。

- Tobias

---

由于POST负载的语义取决于实现者，因此如果没有其他更具体的操作适用，则应采用POST请求作为HTTP操作的瑞士军刀。 POST不仅是创建资源操作... - Roman Vottner

Answer 3

肯定要使用查询参数进行GET请求。这样更有可能被缓存。

如果服务器上的数据模型没有发生任何变化，你的请求应该是GET。服务器操作如日志记录是可以的，但是创建一个过滤器（如其他答案所建议的），与查询缓存不同，是不可以的。

- Nicholas Shanks