端到端的超媒体 REST API 设计

  • Jan Stenberg
  • 邵思华

2015 年 7 月 12 日

话题:SOAREST语言 & 开发架构

Jimmy Bogard在他的一系列博客帖子中表示:REST 是一种定义良好的架构风格,它能够为我们带来许多益处,但也经常被误用于描述各种各样的 Web API。他特别着重描述了实现一个从服务器到客户端的端到端超媒体解决方案所必需的步骤,包括如何选择一种富超媒体的媒体类型(media type)。

Bogard 是一位微软的 MVP,他强调说,REST 以及超媒体这种REST 的约束会大大提高客户端与服务端 API 设计的复杂性。他认为只有在某些场景中才值得这么做,尤其是在客户端与服务端分别独立进行设计的情况下。如果客户端与服务端代码共存于一个源代码控制库,并且还是同时进行部署的,那么超媒体在这种情况下为他提供不了多少价值。

至于如何选择一种媒体类型,Bogard 认为有这么三种选择:

  • 选择某个现有标准。
  • 对某个现有标准进行扩展。
  • 设计属于自己的媒体类型。

考虑到设计一种媒体类型所需的精力,这已远不是在一个项目中就能够完成的工作了,因此他倾向于尽可能选择一种标准的媒体类型。在对不同的媒体类型的能力进行比较时,他提到了Mike Amundsen所设计的H Factor,这项工具能够衡量某个媒体类型对于超媒体的支持等级,帮助他做出适合于当前场景的最佳选择。不过,他往往发现所选择的媒体类型无法满足他的所有需求,因此不得不对所缺失的部分进行扩展。

Bogard 认为服务端的设计与实现是非常直观的,这与创建一个纯粹的 JSON API 差别不大,只是增加了一个更丰富的超媒体模型的复杂性。通常来说,包含所选择的媒体类型的 API 在实现之后还要接受调用者的检验,从客户端的角度对其进行验收。

至于客户端方面,Bogard 在文中提到,他所见到的大多数 REST 示例虽然包含了服务端的 API,但往往未能提供实际的实例,使客户端了解如何调用它们。在 Bogard 的示例中,他创建了一个 web 客户端,其中包含了一个基本的导航视图。 视图中包括了一些信息表,用户可通过这些信息配合在服务端响应中所包含的关系与链接查看详细的内容。服务端返回的响应中包括了大量的元数据,为了保持 REST 风格所提供的松耦合能力,客户端必须由这些元数据所驱动。但 Bogard 依然认为,客户端应当为某个特定的目的而设计,要打造一个泛用目的的客户端是非常无趣的。除了使用 jQuery 设计客户端之外,他还描述了如何使用React设计并实现客户端,由于 React 带有面向组件的特性,因此在 Bogard 看来,它能够非常完美地配合超媒体的使用。

查看英文原文Design of a Hypermedia REST API Server and Consuming Client

SOAREST语言 & 开发架构