如何设计RESTful搜索/过滤？[关闭]

我目前正在用PHP设计和实现RESTful API。但是，我一直无法实现我的初始设计。

GET /users # list of users
GET /user/1 # get user with id 1
POST /user # create new user
PUT /user/1 # modify user with id 1
DELETE /user/1 # delete user with id 1

到目前为止，还算标准，对吗？

我的问题是第一个GET /users。我正在考虑在请求正文中发送参数以过滤列表。这是因为我希望能够指定复杂的过滤器而无需获取超长网址，例如：

GET /users?parameter1=value1&parameter2=value2&parameter3=value3&parameter4=value4

相反，我想拥有类似的东西：

GET /users
# Request body:
{
    "parameter1": "value1",
    "parameter2": "value2",
    "parameter3": "value3",
    "parameter4": "value4"
}

它更具可读性，并为您设置复杂的过滤器提供了极大的可能性。

无论如何，file_get_contents('php://input')没有返回请求正文的GET请求。我也尝试了http_get_request_body()，但是我使用的共享主机没有pecl_http。不确定它是否会有所帮助。

我发现了这个问题，并意识到GET可能不应该具有请求正文。这还没有定论，但他们建议不要这样做。

所以现在我不确定该怎么办。您如何设计RESTful搜索/过滤功能？

我想我可以使用POST，但这似乎并不十分RESTful。

实现RESTful搜索的最佳方法是将搜索本身视为资源。然后，因为您正在创建搜索，所以可以使用POST动词。您不必从字面上在数据库中创建内容即可使用POST。

例如：

Accept: application/json
Content-Type: application/json
POST http://example.com/people/searches
{
  "terms": {
    "ssn": "123456789"
  },
  "order": { ... },
  ...
}

您正在从用户的角度创建搜索。这的实现细节无关紧要。一些RESTful API甚至可能不需要持久性。这是一个实现细节。

如果在GET请求中使用请求正文，则会违反REST原则，因为您的GET请求将无法被缓存，因为缓存系统仅使用URL。

更糟糕的是，您的URL无法添加书签，因为该URL不包含将用户重定向到此页面所需的所有信息。

使用URL或查询参数代替请求正文参数。

例如：

/myapp?var1=xxxx&var2=xxxx
/myapp;var1=xxxx/resource;var2=xxxx 

实际上，HTTP RFC 7231表示：

GET请求消息中的有效负载没有定义的语义。在GET请求上发送有效内容正文可能会导致某些现有实现拒绝该请求。

欲了解更多信息，请看这里

似乎可以以RESTful方式实现资源过滤/搜索。这个想法是要引入一个称为/filters/或的新端点/api/filters/。

使用此端点过滤器可以视为一种资源，因此可以通过POST方法创建。当然，这种方法可以使用body来携带所有参数，并且可以创建复杂的搜索/过滤器结构。

创建此类过滤器后，有两种方法可以获取搜索/过滤器结果。

1. 具有唯一ID的新资源将与201 Created状态码一起返回。然后，使用该ID GET可以发出/api/users/类似的请求：

   GET /api/users/?filterId=1234-abcd
   

2. 通过创建新过滤器后，POST它不会201 Created与303 SeeOther一起回复，但会立即与Location指向的标头一起回复/api/users/?filterId=1234-abcd。此重定向将通过基础库自动处理。

在这两种情况下，都需要提出两个请求以获取过滤后的结果-这可能被认为是一个缺点，尤其是对于移动应用程序而言。对于移动应用我会使用单一POST调用/api/users/filter/。

如何保留创建的过滤器？

它们可以存储在DB中，以后再使用。它们也可以存储在某些临时存储中，例如redis，并具有一些TTL，之后它们将过期并被删除。

这个想法有什么好处？

过滤器，过滤结果是可缓存的，甚至可以加为书签。

我认为您应该使用请求参数，但前提是没有适当的HTTP标头来完成您想做的事情。在HTTP规范没有明确说，这GET不能有身体。但是，本文指出：

按照约定，当使用GET方法时，标识资源所需的所有信息都编码在URI中。HTTP / 1.1中没有用于安全交互（例如，检索）的约定，在这种约定中，客户端在HTTP实体主体中而不是在URI的查询部分中向服务器提供数据。这意味着为了安全操作，URI可能很长。

当我使用laravel / php后端时，我倾向于使用以下内容：

/resource?filters[status_id]=1&filters[city]=Sydney&page=2&include=relatedResource

PHP自动将[]参数转换为数组，因此在此示例中，我将得到一个$filter变量，该变量保存过滤器的数组/对象，以及页面和我希望加载的任何相关资源。

如果您使用其他语言，这可能仍然是一个很好的约定，您可以创建一个解析器以转换[]为数组。

如果您的初始API是否完全是RESTful（尤其是处于alpha阶段），请不要担心太多。首先让后端管道工作。您始终可以进行某种形式的URL转换/重写以将其映射出来，反复进行完善，直到获得足够稳定的东西以进行广泛的测试（“测试版”）为止。

您可以定义URI，这些URI的参数由URI本身上的位置和约定编码，并以一个您将始终映射到某物的路径作为前缀。我不了解PHP，但我会假设存在这样的设施（因为其他语言和Web框架中也存在）：

.ie。使用“ param [i] = value [i]”对商店＃1上的i = 1..4进行“用户”类型的搜索（使用value1，value2，value3，...作为URI查询参数的简写）：

1) GET /store1/search/user/value1,value2,value3,value4

要么

2) GET /store1/search/user,value1,value2,value3,value4

或如下所示（尽管我不建议这样做，以后再介绍）

3) GET /search/store1,user,value1,value2,value3,value4

使用选项1，您可以将所有带有URI前缀的URI映射/store1/search/user到搜索处理程序（或任何PHP名称），默认情况下将在store1下搜索资源（等效于/search?location=store1&type=user。

根据API记录和实施的约定，参数值1到4以逗号分隔并按该顺序显示。

选项2将搜索类型（在本例中为user）添加为位置参数＃1。任一种选择只是一种外观选择。

选项3也是可行的，但我认为我不喜欢它。我认为在某些资源内进行搜索的能力应在搜索本身之前的URI本身中呈现（好像在URI中清楚地表明搜索是在资源内特定的一样）。

相对于在URI上传递参数而言，此方法的优点是搜索是URI的一部分（因此将搜索视为一种资源，一种资源的内容会随着时间的推移而会改变。）缺点是参数顺序是强制性的。

一旦执行了这样的操作，就可以使用GET，它将成为只读资源（因为您无法对其进行POST或PUT操作-GET时将对其进行更新）。它也将是仅在调用时才存在的资源。

通过将结果缓存一段时间或使用DELETE导致缓存被删除，还可以为其添加更多语义。但是，这可能与人们通常使用DELETE的目的背道而驰（并且因为人们通常使用缓存头来控制缓存）。

您如何去做将是一个设计决定，但这就是我要去做的方式。这并不完美，我敢肯定在某些情况下这样做并不是最好的选择（特别是对于非常复杂的搜索条件）。

仅供参考：我知道这有点晚了，但是对任何有兴趣的人来说。取决于您想要的RESTful程度，您将必须实现自己的过滤策略，因为HTTP规范对此并不十分清楚。我想建议对所有过滤器参数进行url编码

GET api/users?filter=param1%3Dvalue1%26param2%3Dvalue2

我知道这很丑陋，但是我认为这是最RESTful的方式，应该可以在服务器端轻松解析:)