web-services - 如何为 RESTful API 中的参数提供有效值列表？

Question

我想这更像是一个概念性问题而不是技术问题。假设我有一个 REST API 来处理庞大的租车车队。

API 以非常标准和连贯(即使有争议)的方式围绕业务实体/资源建模，如下所示:

/cars/1234 - 某辆车的详细数据

/clients/5678 - 某个客户的详细数据

/cars - 汽车列表及其 URI

/clients - 客户名单

然而，车队庞大，所有汽车的 list 并不是那么有用。我宁愿对其进行过滤，例如:

GET /cars?type=minivan

为了正确使用“ type”参数，我应该有一个有效值的列表，例如“小型货车”、“敞篷车”、“旅行车”、“两厢车”、“轿车”等。好吧，没有那里有很多种类的汽车，但让我们假设这个列表对于 API 的 Swagger 定义中的枚举来说太大了。

那么...... REST API 为这样的查询参数提供有效值列表的最一致和最自然的方式是什么？

作为下级资源，如 /cars/types ?这将打破 /cars/{id} URL 模式，不是吗？

作为单独的资源，例如 /tables/cars/types ?这会打破围绕商业模式本身主要资源的一致性，对吧？

作为 OPTIONS /cars 响应正文的一部分?对我来说，这看起来像是“RESTfullest”方式，但我的一些同事不同意，而且 OPTIONS 似乎很少用于这样的事情。

也许作为对 GET /cars?&metadata=values 的回应的一部分或类似的东西？这里的“值”似乎与返回的数据在语义上比与查询参数更相关，不是吗？

还要别的吗？

我已经用谷歌搜索并搜索了关于这个特定主题的一些建议，但我找不到任何东西来帮助我提出这样一个决定的论据......

谢谢!

法布里西奥·罗查

巴西利亚, 巴西

Answer 1

"a good REST API is like an ugly website" -- Rickard Öberg

那么你将如何在网站上做到这一点？好吧，您可能有一个指向表单的链接，该表单将有一个列表控件/单选按钮，其中包含每个选项的语义提示，期望用户从可用选项中选择一个值，并且提交表单时，用户代理会将该值编码到 GET 请求的 URL 中。

所以在 REST 中，你做同样的事情。在最初的回复中，您将包含一个指向“表单”资源的链接；当用户代理获取表单资源时，您返回表单的超媒体表示，其中包含可用选项，当表单提交时，您的资源从标识符的查询部分中选择客户端选项。

但是您可能没有在做 REST:它是一个巨大的 PITA，并且 REST 架构约束的好处可能不会在您的上下文中得到返回。因此，您可能只是在为返回带有选项列表的消息的资源寻找标识符的合理拼写。

As a subordinated resource like /cars/types ? This would break the /cars/{id} URL pattern, isn´t it?

假设您的路由实现可以处理歧义，这是一个不错的选择。您可能会考虑是只有一个列表，还是针对不同上下文的不同列表，以及如何处理。

As a separate resource such as /tables/cars/types? This would break the consistency around the main resources of the business model itself, right?

还记得面向对象编程和封装吗？将 API 与底层数据模型解耦是一件好事。

也就是说，我个人不喜欢将“表格”作为层次结构中的一个元素。如果你想朝那个方向发展，我建议 /dimensions -- 如果您正在设计 data warehouse，您可能会使用该拼写

As part of the body of a response for OPTIONS /cars ? It looks like the "RESTfullest" way to me, but some of my coworkers disagree, and OPTIONS seems to be rarely used for things like that.

哎呀! RFC 7231表明这是一个非常令人困惑的想法。

The OPTIONS method requests information about the communication options available for the target resource, at either the origin server or an intervening intermediary.

(强调)。在为 Web 编写 API 时，您应该始终牢记客户端请求可能会通过您无法控制的中介；您在这些情况下提供良好体验的能力取决于不会因偏离统一界面而混淆中介。

Maybe as part of a response to GET /cars?&metadata=values or something alike?

在大多数情况下，机器对任何拼写都非常满意。 URI 设计指南通常侧重于人类受众。我认为特定的拼写会混淆您的人类消费者，尤其是如果 /cars?...否则将标识作为搜索结果的资源。

Anything else? I still feel that what people expect to find under /cars is... a bunch of cars (their representations, I mean), not a list of values among them...

所以让我们稍微改变一下你的问题

What would be the most consistent and natural way for a REST API to document a list of valid values for a query parameter like that?

如果说网络真正适合做一件事，那就是记录事物。选择几乎所有记录良好的 Web API，并仔细注意您在何处阅读有关端点的信息——这会给您一些好主意。

例如，您可以查看 StackExchange API，其中

https://api.stackexchange.com/docs/questions

告诉你你需要知道的关于资源家族的一切

https://api.stackexchange.com/2.2/questions

不出所料，类型记录如下:

https://api.stackexchange.com/docs/types/flag-option

如果您想对此感兴趣，您可以使用 Accept-Type 协商重定向到人类可读文档或机器可读文档。