Question

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

GET / users

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

GET / users？surname = Harvey＆amp; maxResults = 25

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

提前谢谢！

Answer 1

使用URI template spec当前草稿中描述的语法：

/users{?surname,maxresults}

Answer 2

另一种选择是使用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，并且可以使用您希望放在那里的任何其他文档进行注释。

Answer 3

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

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

定义搜索描述的媒体类型，假设application/prs.example.searchdescription+json（但请注意本答案末尾的P.S.）;
公开代表用户搜索的子资源/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。

P.S。：当我最初写这篇文章时，我还没有意识到定义新媒体类型一直存在问题。 Mark Nottingham blogged about "media type proliferation" and how to combat it the profile link relation使用Here。

如何使用HATEOAS和查询参数进行RESTful搜索？

3 个答案: