通过 URI 与查询字符串设计 REST api

Question

假设我有三个相关的资源，如下所示：

Grandparent (collection) -> Parent (collection) -> and Child (collection)

上面描述了这些资源之间的关系，如下所示：每个祖父母可以映射到一个或多个父母。每个父母可以映射到一个或几个孩子。我希望能够支持搜索子资源但使用过滤条件：

如果我的客户向我传递了对祖父母的 id 引用，我只想搜索作为该祖父母的直系后裔的孩子。

如果我的客户向我传递了对父母的 id 引用，我只想搜索我父母的直系后代的孩子。

我想过这样的事情：

GET /myservice/api/v1/grandparents/{grandparentID}/parents/children?search={text}

和

GET /myservice/api/v1/parents/{parentID}/children?search={text}

分别满足上述要求。

但我也可以这样做：

GET /myservice/api/v1/children?search={text}&grandparentID={id}&parentID=${id}

在这个设计中，我可以允许我的客户在查询字符串中传递给我一个或另一个：grandparentID 或 parentID，但不能同时传递。

我的问题是：

1) 哪种 API 设计更加 RESTful，为什么？从语义上讲，它们的意思和行为方式相同。 URI 中的最后一个资源是“children”，有效地暗示客户端正在对子资源进行操作。

2) 在客户的可理解性和设计师的可维护性方面，每种方法的优缺点是什么。

3) 除了对资源进行“过滤”之外，查询字符串还真正用于什么？如果您使用第一种方法，过滤器参数将作为路径参数而不是查询字符串参数嵌入在 URI 本身中。

谢谢！

Answer 1

需要注意的是，由于您在上述示例中使用了 GET， 取决于最终用户浏览器设置、代理设置或其他调用应用程序内部设置， 响应可能会缓存在消息路由的某个位置，并且原始请求消息可能永远不会真正到达访问最新数据的 API 层。 因此，首先，您可能需要查看使用动词 GET 的要求。 如果您希望您的 API 每次都返回最新数据，则不要使用 GET，或者如果您仍想使用 GET，则要求调用方在 url 末尾附加一个随机数，以减少可能缓存的引擎盖。 或者让客户端在每次 GET 之后发送动词 PURGE。

这种存在于互联网、浏览器和服务器架构中的代理缓存行为是 REST 对我来说失败的地方，因为 GET 的缓存可能非常有用，但只是有时。 如果您想让最终开发人员非常简单并且响应缓存对您没有任何问题，请坚持使用基本查询字符串， 或者 只需使用 POST 并忘记这个令人厌烦的 REST 参数