REST HATEOAS:客户端如何发现Uri或应用于客户端应用程序的筛选器的未来操作？

Question

REST约束HATEOAS [https://en.wikipedia.org/wiki/HATEOAS]的维基页面建议：

“REST客户端通过简单的固定URL进入REST应用程序。客户端将来可能采取的所有操作都是在服务器返回的资源表示形式中发现的。”

我们正在创建一个类似于电子商务网站的产品搜索页面。我们目前为用户提供了1.根据预算过滤产品的选项，即输入最小和最大预算，以及2.过滤掉“脱销”产品的选项。

目前，当有人输入最低和最高预算时，客户端将创建以下Uri来获取产品列表：

/api/products/?预算={min}-{max}，即/api/products/?预算=1-3

或者，如果有人选择排除“脱销”产品，客户端将创建以下Uri来获取产品列表：

/api/products/?outofstock=false

我觉得我们违反了HATEOAS原则，在每个客户端硬编码这些链接，因为HATEOAS建议客户端应该发现除简单的固定URL之外的所有资源。这真的是一种违规行为，还是这是唯一的办法？

Answer 1

在您的示例中，您已经将/products建模为一个REST资源，表示多个产品的集合。budget和outofstock都在过滤限制返回产品的查询参数。

您可以使用RFC6570中定义的URI模板来向客户宣布您的REST API支持这些查询参数。

{
    "links": [
        {
            "rel": "products",
            "href": "/products{?budget,outofstock}"
        }
    ]
}

这将向客户端宣布这些参数的存在，但不一定是它们接受的值的数据类型。我的理解是，标准并没有像指定值那样形式化地指定数据类型，但是有一些选项可以用来指定该信息，比如JSON Hyper-Schema。据我所知，这是一份IETF草案。

另一种选择是响应包括预先填充了相关查询参数的专用链接。客户端可以提供到这些链接的导航，而不需要对服务正在使用的特定查询参数进行硬编码。

{
    "links": [
        {
            "rel": "budget-low",
            "href": "/products?budget=1-3"
        },
        {
            "rel": "in-stock",
            "href": "/products?outofstock=false"
        }
    ]
}

Answer 2

我觉得我们违反了HATEOAS原则，在每个客户端硬编码这些链接，因为HATEOAS建议客户端应该发现除简单的固定

之外的所有资源。这真的是一种违规吗？

是。

HATEOAS方法是将语义知识构建到客户端中，然后客户端在表示中搜索适当的语义，并遵循找到的任何链接。

你可以通过思考如何在网站上与人类消费者一起做这件事来获得REST设计。你会告诉他们书签，当他们加载该页面时，他们会看到带有文本的超链接，告诉他们每个链接的用途。单击范围搜索的链接将把他们带到一个表单，文本标签将告诉他们每个字段的用途。他们将填写并提交表单，该表单(对于GET)将按照html媒体类型的规范中所描述的那样构造一个URI，并且他们将获得结果。背。

这就是工作中的超媒体。从那里开始，然后添加机器可读的提示，以便客户端可以在表示中找到链接。

你能分享一些链接/例子吗，在这些例子中，有些东西已经构建好了，请记住这些

有一段时间，Sun Cloud API是超媒体应用编程接口最受欢迎的演示。

对于当前通用的示例，RFC 4287: Atom Syndication Format和RFC 5023: Atom Publication Protocol可能是最好的选择。

我想设计这样的东西，但又不能得到确切的"html媒体类型“如何才能做到这一点？

创建您自己的自定义媒体类型？您可以这样做；但使用现有的一种超媒体格式(HTML、HAL、JSON-LD...)可能会更有效。Kevin Sookocheff写了几种类型的overview (2014)。

Answer 3

HATEOAS的目的是保持服务器对URL空间的控制。好处是使客户端对向后不兼容的更改更具弹性。问题是你需要多大的弹性。

1. 如果你的客户被强制硬编码整个网址，那就没有弹性了。任何URL更改都会破坏客户端。
2. 如果您的客户端获取了基本URL，但对URL参数进行了硬编码，则您可以更改基本路径，但您不能更改参数或查询语义。
3. 如果您的服务器正在返回带有基本URL和查询参数的URL模板，则您的客户端对更改的适应能力更强，但如果客户端随意选择参数，则仍然无法更改查询语义。例如，假设您的客户经常进行一个特定的查询，而您决定提供一个单独的带有优化的URL，甚至是一个静态资源。客户端不会立即开始使用它，客户端开发人员将不得不更改所使用的代码和参数，即使您在网址模板中提供了它们。
4. 如果您的服务器为所有相关查询提供了单独的链接或带有固定参数的网址模板，您可以在任何时间随意更改它们，而不会中断客户端，但这需要更多的工作。

所以，如果你只想把HATEOAS作为一个目的，那么就做4，这就是它应该做的。如果你有一个真正的问题要解决，那么不要担心违反HATEOAS，问问你自己需要多少弹性，你可以投入多少工作。

请注意，没有任何东西强迫您在整个API中甚至在相同的资源中使用相同的方法。例如，您可以使用选项3来提供更灵活的查询，使用选项4来提供一些将来可能需要优化的常见查询。

请记住，如果客户不使用HATEOAS，那么您为使HATEOAS正确所做的所有努力都将是毫无意义的。如果他们硬编码URL而不是使用链接，您的更改将破坏它们，即使您努力避免这种情况。这可能是个问题，也可能不是，这取决于你的公司文化。