RESTful API设计：查询参数的列表值选项

Question

假设您正在构建一个API，该API返回以下位置的资源列表：

[GET] /resources
=> 
[
 {.. id: 1, foo: "A" ..}, {.. id: 2, foo: "B" ..}, {.. id: 3, foo: "A" ..}
]

可以使用query param进行过滤：

[GET] /resources&foo=A
=>
[
 {.. id: 1, foo: "A" ..}, {.. id: 3, foo: "A" ..}
]

到现在为止还挺好。

现在要求您创建一个端点，该端点返回foo的可用值；
您希望哪个端点返回可用于过滤资源的选项？

---

我的建议是使用HTTP方法OPTIONS ：

此方法允许客户端确定与资源相关联的选项和/或要求，或服务器的功能，而无需暗示资源操作。

[OPTIONS] /resources
=> 
{
  foo: ["A","B"]
}

但是，恐怕此HTTP方法旨在描述连接本身，例如HTTP动词或CORS，而不是描述数据的域。

Answer 1

确实，正确地说明选项方法是为通信选项保留的，但不是内容的，它用于CORS验证。

我将使用以下任一方法：

• GET / resourceTypes？field = foo
• GET / resource / types？field = foo

您可以将“类型”替换为更有意义的内容，例如“ allowedValues”，“ enum”等。

通常，以我的经验，在REST中，可过滤值是事先已知的，或者您有一个没有预定值的自由搜索字段。

Answer 2

您的实际问题针对的是如何教客户如何使用某些资源的选项。 如果您仔细研究一下Web和HTML，您可能会发现HTML使用Forms来教浏览器（= clients）服务器期望客户端输入的内容以及发送请求之前可以进行的选择。

HTML规范包含有关可在表单中使用的各个元素的语法和语义的描述。 这样，服务器可以发送选项元素，以使客户端在几个或多个选项之间进行选择。 当前，有一些草案试图将这一概念转换为HTML以外的其他表示形式，但是据我所知，它们中的任何一个都还不够重要或尚未得到广泛接受。 其中有一些基于JSON的格式 ，例如hal-form ， halform ， ion和hydra 。

根据菲尔丁

REST API应该花费几乎所有的描述性精力来定义用于表示资源和驱动应用程序状态的媒体类型，或者为现有标准媒体类型定义扩展关系名称和/或启用超文本的标记。 花费的所有精力描述应该在媒体类型的处理规则范围内（并且在大多数情况下已由现有媒体类型定义）完全定义要在感兴趣的URI上使用的方法。

对于真正的REST客户端， application/json并不是一种很好的表示形式，因为它缺乏语义来描述类似表单的表示形式可能具有的各个元素，并且缺少处理规则，该表示形式的使用者应如何正确处理信息。 在这里，上面提到的一种媒体类型肯定是有益的。 问题不应该是选择哪一个，而是要支持多少。 您支持的格式越多，任意客户端越有可能与您的系统进行交互。

客户端和服务器应始终使用内容类型协商来达成双方都同意交换数据的表示形式。 由于两个客户都知道如何处理和解释约定的媒体类型，因此减少了互操作性问题。 如果没有可用的通用表示格式，或者客户端发送了服务器不熟悉的表示形式，则服务器将通知客户端其无法为客户端提供内容。

围绕REST的整个目的是允许服务器将来自由发展，而不必担心破坏客户端。 在具有许多不受您控制的不同客户端和API的区域中，这尤其有利。 EDI就是这样一个领域，可以为您提供更好的可视化效果。 在这里，许多ERP系统和应用程序必须交换业务文档，例如订单和发票。 尽管有大量使用的自定义格式，但有两种标准化的表示格式，例如EDIFACT，这使整个领域变得非常有趣。 基本上，您不想为要与之交互的每个ERP系统创建一个自定义的客户端（或服务器），而是要平等地处理每条消息。

对于前端到后端通信，尽管您实际上并不需要完全成熟的REST体系结构，因为这可能给您带来更多负担，而不是它提供的任何好处。 REST中的真相是，必须仔细设计客户端和服务器，以避免耦合。 如果只有一个参与者试图忽略其中一个约束，那么现场部署的机会就存在，这种耦合会阻止服务器将来添加新功能而不影响客户端或客户端保持与服务交互的能力。

因此，如果您想教客户关于某些资源的选择，请在Web上定位并使用能够表达该功能的媒体类型，以便客户可以使用它。