RESTful API需要查询字符串中的参数？

Question

在设计RESTful API时,如果GET请求仅在与请求关联的特定参数时才有意义,该怎么办？参数是否应作为查询字符串传递,如果是,那么在未指定所有参数或格式不正确时该怎么办？

例如,假设我有一个Post资源,可以通过`api/posts`端点访问.每个帖子都有一个地理位置,只有在指定帖子可能所在的区域时才能检索帖子.因此,需要3个参数:纬度,经度和半径.

在这种情况下,我可以考虑2个选项:
1.将参数放在查询字符串中:api/posts/?lat=5.54158&lng=71.5486&radius=10
2.将参数放在URL中:api/posts/lat/5.54158/lng/71.5486/radius/10

哪一个是正确的方法？将所需参数放在查询字符串中似乎是错误的,但后一种方法感觉有点'丑陋'.

PS.我知道有很多关于这个主题的讨论(例如:REST API最佳实践:在哪里放置参数？),但我的问题专门针对需要参数的情况,而不是可选的.

Answer 1

第一种方法更好.

api/posts/?lat=5.54158&lng=71.5486&radius=10

第二种方法有点误导.

api/posts/lat/5.54158/lng/71.5486/radius/10

您应该将每个目录视为资源.在这个原因中,子资源(例如:"api/posts/lat/5.54158")不是真正的资源,因此具有误导性.在某些情况下,这种模式是一个更好的解决方案,但是看看给出了什么,我会使用查询字符串.除非你有一些实体链接直接链接到这个URL,我真的不喜欢它.

Answer 2

您应该将所有内容放入查询字符串中，并将服务器设置为在未接收到3个必需参数时返回错误代码。

因为它是标识对象的一组参数。

以这个例子为例：lat = 5.54158; lng = 71.5486半径= 10

这个网址不太可能有意义：

api/posts/lat/5.54158/lng/yyyy/radius/zz

它不同于：

api/memb/35/..

因为ID为35的成员可以具有以下许多功能（因此，有效的url）：

api/memb/35/status 要么 api/memb/35/lastlogin

Answer 3

在设计 RESTful API 时，如果 GET 请求仅在存在与请求关联的特定参数时才有意义，该怎么办？参数是否应该作为查询字符串传递，如果是，当所有参数未指定或格式不正确时该怎么办？

通过 REST，您的 API 必须满足 REST 约束，这些约束在Fielding 论文中进行了描述。这些约束之一是统一接口约束，其中包括HATEOAS 约束。根据 HATEOAS 约束，您的 API 必须提供标准超媒体格式作为响应。该超媒体包含用元数据（例如链接关系或RDF注释）注释的超链接（例如HTML链接、表单）。客户端检查元数据，元数据向他们解释超链接的作用。之后，他们可以决定是否要点击该链接。当他们点击链接时，他们可以根据 URI 模板、参数等构建 HTTP 请求，并将其发送到 REST 服务。

在您的情况下，使用哪种 URI 结构并不重要，它仅用于服务使用，因为客户端始终使用给定的 URI 模板，并且客户端不关心该模板中的内容，直到它是一个有效的 URI 模板为止。填写参数。

在大多数情况下，您的客户端有足够的验证信息来测试参数是否不正确或丢失。在这种情况下，它不会发送 HTTP 请求，因此您在服务中无需执行任何操作。如果无效参数通过，那么在您的情况下，您的服务会发回 404 - 未找到，因为 URI 是资源标识符，并且没有资源属于无效 URI（从给定 URI 模板和无效参数生成）。