RESTful API运行时可发现性/ HATEOAS客户端设计

Question

对于我参与的SaaS初创公司，我正在构建一个RESTful Web API和几个使用它的不同平台上的客户端应用程序。我想我已经找到了API，但现在我转向客户了。正如我一直在阅读有关REST的内容，我发现REST的一个关键部分是 discovery ，但是对于发现的真正含义的两种不同解释之间似乎存在很多争论：

1. 开发人员发现：开发人员将大量API详细信息硬编码到客户端，例如资源URI，查询参数，支持的HTTP方法以及他们发现的其他详细信息通过浏览文档和试验API的响应。这种类型的发现IMHO需要很酷的链接和API版本问题，并导致客户端代码与API的硬耦合。没有比使用详细记录的RPC集合好多了。

2. 运行时发现 - 客户端应用程序本身能够在很少或没有带外信息的情况下找出所需的一切（可能只是了解API的媒体类型）处理。）链接可能很热。但是为了使API非常高效，似乎需要大量的查询参数链接模板，这会使带外信息重新出现。由于我没有，可能还有其他一些我没有想到的困难。在发展中得到了这一点。但我确实喜欢松耦合的想法。

运行时发现似乎是REST的圣杯，但我看到很少讨论如何实现这样的客户端。几乎所有我发现的REST源似乎都假设开发人员发现。有人知道一些运行时发现资源吗？最佳做法？具有实际代码的示例或库？我正在为一个客户端使用PHP（Zend Framework）。 Objective-C（iOS）为另一个。

鉴于开发人员社区中目前的一系列工具和知识，运行时发现是否是一个现实的目标？我可以编写我的客户端以不透明的方式处理所有URI，但如何最有效地执行此操作是一个问题，尤其是在低带宽连接上。无论如何，URI只是等式的一部分。如何在运行时上下文中链接模板？除了提出大量的OPTIONS请求之外，如何传达支持哪些方法？

Answer 1

在此视频中，Jon Moore使用运行时HATEOAS自动发现构建了一个通用客户端。它非常令人印象深刻，值得一看：

http://oredev.org/oredev2010/2010/sessions/hypermedia-apis.html

Answer 2

这绝对是一个难以破解的难题。在Google，我们已经实施了我们的发现服务，我们所有的新API都是针对这些服务构建的。 TL; DR版本是我们生成一个类似JSON Schema的规范，我们的客户端可以解析它们 - 其中许多是动态的。

这一结果意味着开发人员可以更轻松地进行SDK升级，并为我们提供简单/更好的维护。

绝不是完美的解决方案，但我们的许多开发人员似乎都喜欢。

有关详细信息，请参阅link（并确保观看视频。）

Answer 3

魅力。你所描述的基本上是HATEOAS原则。你问的是什么是HATEOAS？阅读：http://en.wikipedia.org/wiki/HATEOAS

通俗地说，HATEOAS意味着链接跟随。这种方法将您的客户与特定网址分离，并使您可以灵活地更改API而不会破坏任何人。

Answer 4

你完成了自己的家庭工作而你已经掌握了它的核心：运行时发现是圣杯。不要追逐它。

UDDI讲述了运行时发现的一个令人痛苦的故事：http://en.wikipedia.org/wiki/Universal_Description_Discovery_and_Integration

Answer 5

在调用API“RESTful”之前应该满足的一个要求是，应该可以在该API之上编写通用客户端应用程序。使用通用客户端，用户应该能够访问所有API的功能。通用客户端是一种客户端应用程序，它不假定任何资源具有超出媒体类型定义的结构的特定结构。例如，Web浏览器是一个知道如何解释HTML的通用客户端，包括HTML表单等。

现在，假设我们有一个用于网上商店的HTTP / JSON API，我们希望构建一个HTML / CSS / JavaScript客户端，为我们的客户提供出色的用户体验。让该客户端成为通用客户端应用程序是否是一个现实的选择？不。我们希望为每个特定的数据元素和每个特定的应用程序状态提供特定的外观。我们不希望在API中包含有关这些特定于演示文稿的所有知识，相反，客户端应该定义外观并且API应该只携带数据。这意味着客户端具有特定资源元素与特定布局和用户交互的硬编码耦合。

这是HATEOAS的结束，因此是REST的结束？ 是和否。

是，因为如果我们将有关API的知识硬编码到客户端，我们就会失去HATEOAS的好处：服务器端更改可能会破坏客户端。

否，原因有两个：

1. “RESTful”是API的属性，而不是客户端的属性。只要理论上 ，为了构建一个提供API所有功能的通用客户端，API就可以称为RESTful。客户端不遵守规则的事实不是API的错。通用客户端具有糟糕的用户体验这一事实不是问题。如果我们实际上没有那个通用客户端，为什么知道可能拥有通用客户端是多么重要？这让我想到了第二个原因：
2. RESTful API为客户提供了选择他们想要的通用程度的选项，即他们想要的服务器端更改的弹性。需要提供出色用户体验的客户端仍然可以适应URI更改，默认值更改等。在没有用户交互的情况下进行批处理作业的客户可以适应其他类型的更改。

如果您对实际示例感兴趣，请查看我的JAREST paper。最后一节是关于HATEOAS。您将看到，使用JAREST，即使是高度互动且具有视觉吸引力的客户端也可以非常适应服务器端的变化，但不是100％。

Answer 6

有关基本运行时发现客户端的另一个示例，请查看 HAL Talk Hypermedia API client demo 。

基于超文本应用程序语言（用于链接的XML + JSON模式）：http://stateless.co/hal_specification.html

Answer 7

我认为关于HATEOAS的重点不是它是一些圣杯客户端，而是它将客户端与URI更改隔离 - 假设您使用已知（或开发者发现的自定义）链接关系将允许系统知道对象的哪个链接是可编辑的表单。重要的是使用具有超媒体感知能力的emdia类型（例如HTML，XHTML等）。

Answer 8

你写道：

  

为了使API非常高效，似乎需要大量的查询参数链接模板，这会使带外信息回归。

如果在先前的请求中提供了该链接模板，则没有带外信息。例如，HTML搜索表单使用链接模板（/search?q=%@）来生成URL（/search?q=hateoas），但客户端（Web浏览器）除了如何使用HTML表单和{{ 1}}。