执行宁静搜索的最佳方式

Question

根据我最近对 ​​REST API 接口所做的大量研究，我有一个理论问题。

首先我明白，在 REST 中，资源应该是名词而不是动词，并且每个资源都应该与下一个资源解耦，但是资源可以返回相同的实体或实体集合，具体取决于资源的用途。

然而，我的重点是执行安静的搜索。

在我所做的所有研究中，我遇到的最常见的解决方案是在 URL 中使用参数

api.test.com/search-cars?param1=val1&param2=val2

虽然这是标准做法，并没有真正违反 REST 规则，但为什么没有人将搜索参数表示为 id（可能是 JSON 的形式）

api.test.com/cars/{"color":"blue","year":"2013","make":"toyota"}

如果我将汽车视为一种资源并将我的 id 表示为 JSON，我可以轻松地说我确实拥有有限数量的汽车，因此我拥有有限且唯一数量的 id。

此外，这通过符合“resource/id”来促进纯粹的休息

在第一个示例中使用参数有什么好处和坏处？

在第二个示例中使用 JSON 作为带有“过滤器”的 id 有哪些优点和缺点？

您的所有 cmets 都会非常有帮助，因为我需要就如何继续使用我的 API 的第一个资源做出最终决定。另外，我需要有一个强有力的论据让我的老板解释我为什么决定采用这两种方法。

Answer 1

URL 的一般形式是

scheme://domain:port/path?query_string#fragment_id

所以你提出了两个网址：

1. 搜索query_string
2. 按最后一个path 段搜索

按query_string搜索

我建议将集合命名为 cars，而不是 search-cars。正如您在问题中所写，URL 标识资源。 cars 资源标识所有汽车的集合。我不知道名为search-cars 的资源会识别什么集合。

GET http://api.test.com/cars

将返回所有汽车的集合。

GET http://api.test.com/cars/123

将退回由123标识的汽车。

GET http://api.test.com/cars?color=blue&year=2013

将返回 2013 年制造的所有蓝色汽车的集合。

按path搜索

您的第二个网址

GET http://api.test.com/cars/{"color":"blue","year":"2013","make":"toyota"}

将使查询 (JSON) 成为路径的一部分。为了使这两个示例相等，我想将 JSON 设为查询参数：

GET http://api.test.com/cars?search={"color":"blue","year":"2013","make":"toyota"} 

JSON 与命名查询参数

大多数 REST 框架支持将查询参数映射到方法参数。

大多数 REST 框架允许您将路径段映射到方法参数。同样，大多数 REST 框架允许您将 JSON 映射到一个对象或一个简单的字典。

让 JSON 更难使用的是需要转义 "{} 字符：

{"color":"blue","year":"2013","make":"toyota"}

变成

%7B%22color%22%3A%22blue%22%2C%22year%22%3A%222013%22%2C%22make%22%3A%22toyota%22%7D

这不是很好。

总结

• 您可以同时使用 URL 的 query_string 和 path 来标识资源。搜索参数最好放在query_string 中，因为? 在心理上可以翻译成SQL 的WHERE。
• 不要在 URL 中使用 JSON，因为转义的 JSON 难以阅读。