REST 搜索 API URI 表单答案

【问题标题】：REST search API URI formREST 搜索 API URI 表单
【发布时间】：2013-03-17 12:52:42
【问题描述】：

我正在实现一个搜索 API，它允许搜索系统中的多种类型的对象（客户端、产品等）。哪种形式的 URI 更可取：

/clients/search
/products/search
...

或

/search/clients
/search/products
...

/clients、/products 资源已用于其他目的。

编辑：

我认为这无关紧要，但似乎确实如此，所以 - 搜索可能足够复杂，需要 POST 而不是 GET

谢谢，

亚历克斯

【问题讨论】：

标签： java rest search naming

【解决方案1】：

这个建议看起来很合理：https://blog.apigee.com/detail/restful_api_design_tips_for_search 所以根据这个：

/clients/search
/products/search
...

高音使用不一致的结构：

Splunk 更喜欢 search 优先的概念：http://docs.splunk.com/Documentation/Splunk/5.0.2/RESTAPI/RESTsearches。

因此，这些示例表明没有单一的最佳方法可以做到这一点。我认为当您想将查询限制为先验已知资源时，最好使用第一个示例。否则使用全局搜索 - /search 将所有其他编码为参数（参见 Freebase API：https://developers.google.com/freebase/v1/search - 他们有自己的查询语言......）。

【讨论】：

【解决方案2】：

如果它是一个 RESTful API，则您不需要在 URI 中使用“搜索”一词，因为产品是资源，而 HTTP 方法 GET 提供了动词。所以你可以做类似的事情；

GET /product/998827727/（通过 id 检索产品）
GET /product/?searchTerm=thingybob（使用搜索词查找产品）

也就是说，有时您的搜索词过于复杂，因此您需要实用资源，因此您可以执行 POST /product-search/ 或 POST /product/search/ 之类的操作，因为产品是主要资源

【讨论】：

是的，它可能足够复杂，需要 POST。那么在这种情况下你会推荐 /products/search 吗？
是的，如果您觉得它需要 POST，我会的。一些铁杆建议您应该对搜索过滤器资源进行 POST，该资源会为搜索生成哈希或唯一 ID，然后执行 GET /product/search-filter/$filterId/ 但如果您有高大量搜索。
我还要确保使用单数资源名称、产品和客户与产品和客户
嗯，也许，但现在这是一个系统范围的约定，并且 API 已经被使用（不多，但仍然），所以我不想改变它。此外，如果您查看浏览器的地址栏，您会看到 .../questions/... :)
采用 REST 唯一一致的地方是实现会不一致...顺便说一句，我推荐 RESTful Cookbook 作为此类决策的模式目录。

【解决方案3】：

恕我直言，这两种方法都是错误的。

问题：如果我向您的服务发送以下 HTTP 请求会得到什么：

GET /clients/search
Host: service.org

GET /products/search
Host: service.org

GET /search/clients
Host: service.org

GET /search/products
Host: service.org

如果 /search 和 /products 资源已经存在，为什么不重复使用它们并在搜索时发送必要的查询参数？例如：

GET /clients?gender=female&country=US
Host: service.org

如果客户端对“/clients”服务的请求将响应所有客户端的列表，如果 URI 包含查询参数服务将响应过滤结果。我认为创建这样的专用搜索资源的价值为零。

附： Twitter 的 URI 很糟糕。

【讨论】：

妈的，你打字比我快！