为RESTful（超媒体）API编写客户端

Question

最近几天，我一直在研究“真正”的RESTful API，并且我认为我已经接近理解它的要点了。

但其中一个让我困惑的事情是，我甚至无法想象如何为“真正”的超媒体API编写客户端：

1. 我读过的大多数例子都是关于浏览器和蜘蛛的，但这并没有什么帮助：一个是人类指导和“智能”的，另一个是愚蠢和“随机”的。就目前而言，我有点感觉你需要学习人工智能才能让客户端正常运行。

2. 有一件事对我来说不太清楚，那就是客户端如何知道在任何给定链接上使用哪个动词？这是否隐含在URI的'rel'类型中？另一种方法（在这里阅读）似乎是使用xhtml并具备可以解析和发布表单的客户端。

3. 一个链接可能会更改，但链接的路径不会更改的可能性有多大？ 在大多数示例中，路径和链接是相同的：

例如，如果我想设置一个客户端，从Toni的蛋糕店带回蛋糕列表：

http://tonis.com
{ link: { type : "cakes" ; uri : "http://tonis.com/cakes" } }

当Toni's变成Toni's Food Shop时，链接变成http://tonis.com/desserts/cakes，会发生什么？

我们是否保留根目录下的初始链接cakes以保持向后兼容性呢？如果不保留，那么对于被告知“前往根目录，在那里寻找蛋糕”的用户代理该如何重定向呢？

我漏掉了什么吗？

- Benjol

---

进一步阅读：对于任何对超媒体API感兴趣的人，请参考以下链接： http://wekeroad.com/2012/03/03/moving-the-philosophy-into-machinery/ http://groups.google.com/group/servicestack/browse_thread/thread/0fc85c0290b499f2?pli=1 http://timelessrepo.com/haters-gonna-hateoas http://restfulie.caelum.com.br/ - Benjol

Answer 1

好的，我也不是REST专家，最近一直在阅读相关书籍，所以我要写的不是我的经验或看法，而是我阅读的内容的总结，特别是REST实践这本书。

首先，客户端和服务器之间不能避免一些初始协议，REST的目标是让它们同意最小的事情，并让各方自己关心自己的东西。例如，客户端不应该关心链接布局或数据在服务器上的存储方式，服务器也不应该关心客户端的状态。他们事先同意的内容（即交互开始之前）是上述书籍作者所称的“领域应用协议”（DAP）。

DAP的重要之处在于它是有状态的，尽管HTTP本身不是（因为任何客户端-服务端的交互都有状态，至少有开始和结束）。这种状态可以用“客户端接下来可以/可能/应该做什么”来描述：“我已经开始使用服务了，现在该怎么办？好的，我可以搜索项目。搜索这个项目，接下来呢？好的，我可以订购这个和那个…等等。”

超媒体内容类型的定义是能够处理数据交换和交互状态。正如我之前提到的，状态是用可能的操作来描述的，而来自REST的“资源”，所有操作都是以可访问资源的形式描述的。我想你已经看到了缩写“HATEOAS（超媒体作为应用程序状态的引擎）”，这就是它的意思。

因此，为了与服务交互，客户端使用双方都理解的超媒体格式，可以是标准的、自定义的或两者混合的（例如基于XML/XHTML）。除此之外，他们还必须共享协议，最可能的是HTTP，但由于一些细节被省略了，必须有一些使用惯例，比如“使用POST创建资源和PUT更新资源”。此外，这样的协议将包括服务的入口点（再次以可访问资源的形式）。

这三个方面完全定义了该域协议。特别地，客户端在开始使用服务之前不应该知道任何内部链接或在交互完成后记住它们。因此，任何对内部导航的更改，例如将/cakes重命名为/f5d96b5c，只要遵循最初的协议并通过前门进入商店，就不会影响客户端。

- bereal

Answer 2

@Benjol

您必须避免针对特定URI编写客户端程序。当您描述链接时，最重要的是其含义而不是URI本身。您可以随时更改URI，但这不应该破坏您的客户端。

我会这样修改您的示例：

{"link": {
  "rel":   "collection http://relations.your-service.com/cakes",
  "href":  "http://tonis.com/cakes",
  "title": "List of cakes",
  "type":  "application/vnd.yourformat+json"
}}

如果有客户端使用您的服务，它需要了解：

- 链接结构本身 - 链接关系（在此情况下，“集合”是RFC和“http://relations.your-service.com/cakes”是您的域特定链接关系）

在这种情况下，客户端只需取消引用“href”属性指定的地址并显示蛋糕列表。稍后，如果更改蛋糕列表提供程序URI，客户端将继续工作，这意味着客户端仍然理解您的媒体类型的语义。

附言： 请参阅已注册的链接关系属性： http://www.iana.org/assignments/link-relations/link-relations.xml Web链接RFC：https://www.rfc-editor.org/rfc/rfc5988

- ioseb