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

Question

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

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升级,并为我们提供简便/更好的维护.

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

有关详细信息,请参阅链接(并确保观看视频.)

Answer 3

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

通俗地说,HATEOAS意味着链接跟随.这种方法将您的客户端与特定的URL分离,并使您可以灵活地更改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 论文。最后一部分是关于 HATEOAS 的。您将看到，使用 JAREST，即使是高度交互且具有视觉吸引力的客户端也可以对服务器端更改具有相当的弹性，尽管不是 100%。