34

我想使用查询参数设计一个 RESTful 搜索 URI。例如，此 URI 返回所有用户的列表：

获取/用户

以及姓氏为“Harvey”的前 25 位用户：

GET /users?surname=Harvey&maxResults=25

如何使用超媒体来描述“/users”资源允许的查询参数？我注意到新的Google Tasks API只是记录了参考指南中的所有查询参数。我会记录这份清单，但我也想用 HATEOAS 来做。

先感谢您！

4

3 回答 3

22

使用当前URI 模板规范草案中描述的语法，您可以：

/users{?surname,maxresults}
于 2011-05-16T19:26:13.657 回答
6

另一种选择是使用 html 表单：

<form method="get" action="/users">
   <label for="surname">Surname: </label>
     <input type="text" name="surname"/>
   <label for="maxresults">Max Results: </label>
     <input type="text" name="maxresults" value="25"/> <!-- default is 25 -->
   <input type="submit" name="submitbutton" value="submit"/>
</form>

像这样的表单完整地记录了可用的选项和任何默认值，它创建了指定的 URL，并且可以用您想要放在那里的任何进一步的文档进行注释。

于 2011-05-17T00:12:24.943 回答
1

我不是 REST 专家，但让我投入我的 2 美分：

在人类 Web 上，HTML 表单通常用于构建表示搜索结果的 URI。问题是，可编程网络没有表格。但是你可以很容易地自己定义一些类似的东西，那就是：

  1. 假设为搜索描述定义媒体类型application/prs.example.searchdescription+json（但请注意此答案末尾的 PS）；

  2. 公开代表用户搜索的子资源，/users/search.

第二步将通过从其他地方链接到该子资源来实现。例如，假设客户已请求GET /users. 它可能会收到这样的信息：

{ _links: [ …, { rel: "search", href: "/users/search" }, …] }

客户端可以按照该链接和POST对该资源 URI 的搜索规范进行搜索，例如：

POST /users/search
…
Content-Type: application/prs.example.search-definition+json
…

{ criteria: { surname: "Harvey" }, maxResults: 25 }

在这里，criteria包含要找到的对象的（部分）表示。这可以做成任意复杂的描述。

对于如上所述的请求，服务器可能会回复状态代码200 OK，并在实体正文中回复表示已发布搜索结果的资源的链接：

{ _links: [ { rel: "results", href: "/users?surname=Harvey&maxResults=25" } ] }

然后，客户端可以导航到具有results关系的 URI 以获取搜索结果，而不必自己组装 URI。

PS：当我最初写这篇文章时，我还没有意识到一直定义新的媒体类型会成为问题。Mark Nottingham 写了一篇关于“媒体类型扩散”以及如何利用链接关系来对抗它的profile博客。

于 2015-06-21T20:06:46.360 回答