构建自描述 RESTFul API 体系的设计与畅想

今天的互联网世界,API 已经无处不在,越来越多的服务依赖 API 交换信息,彼此协作,彼此连接,API 开发协作的体验也越来越重要。

有协作,就有沟通,显而易见的方法就是写文档,用文档描述 API 的用途,使用方法。但如何保持文档与代码的同步确是业界的千古难题,能做得到位的寥寥无几。

难道就真的没有方法了吗?

这就是本文的主题,构建自描述 RESTFul API 体系,如何通过自描述的 API 设计,抹除代码与文档的界限,一切皆代码。

何谓自描述

所谓的自描述,就是让 API 在提供具体的功能的同时,能够提供一些用于描述该 API 的元数据,包括但不限于以下几个方面:

  1. API 的用途,主题以及简介
  2. API 的参数及每个参数的含义
  3. API 的返回结果及每个字段的含义
  4. 相关的 API 或者子 API 的引用

利用这些元数据,再通过合适的工具,对这些元数据予以聚合、展示,便形成了我们能够直观看到的 API 文档~

相比静态的 API 文档,自描述元数据能够提供更加动态的内容,能够依据参数,用户的身份而返回不同的内容,从而更好的适应 API 使用者的需求。

自描述的实现

要完美优雅的实现自描述的 RESTFul API 体系需要从三个层次入手:框架层,协议层和表现层。

框架层

框架层是与具体语言相关的,通过框架的支持,让业务 API 及对应的元数据能更方便的通过 RESTFul 接口对外暴露。

协议层

协议层是框架层和展现层的桥梁和通信规范,框架层和表现层都可以有多个实现,但协议层的规范只有一个。

在 HTTP 的层面,我们可以使用 OPTIONS 请求来获取元数据,这也是符合 HTTP 规范的定义:

This method allows the client to determine the options and/or requirements associated with a resource, or the capabilities of a server, without implying a resource action or initiating a resource retrieval.

表现层

表现层通过可视化的手段,让 API 的元数据更方便被人们所认知和查看。比如通过元数据生成的 API 文档就属于展现层的工具。

自描述与 Swagger API

业内已经有很多的 RESTFul API 文档工具,比如 Swagger API 和 API Blueprint,它们都是很很优秀的生产力工具,不过它们并没有提供自描述的方案支持。

当然,这并不妨碍我们站在巨人的肩膀上,充分复用它们在协议层表现层的成果,更方便快捷的构建自己的自描述 RESTFul API 体系。

背后的理念

做一件事情的方式千千万万,为什么选择这样做,背后是有一套理念的,理念是指导做事方法的原则。

这个理念就是「一切皆代码」,文档亦如是。

这个理念并不是什么新东西,业内有很多先进的生产力工具都是这样做的,比如:

  1. Docker 的 Dockerfile 将构建流程变为代码,让运行环境更具可复制性
  2. 知名持续集成工具 Travis CI 通过 .travis-ci.yml 描述项目构建过程

在应用「一切皆代码」理念的前期下,再通过版本控制软件,将一切的变更记录在案,所有的修改也在同一个地方进行,都在一个地方修改了,想不同步都难。

应用场景

除了上文提到的 API 文档的场景,自描述的 RESTFul API 显然有更多的潜力可被挖掘,下面是简单的介绍。

自动化测试

通过元数据,可对所有的 API 自动的做一些基本的单元测试或者功能测试,从而减轻测试编写所花费的时间。更重要的是,所有的数据都只需要维护一份,比如 API 模型的定义。

服务集成

通过自描述的 RESTFul API ,可以方便的让彼此依赖的服务通过元数据进行信息交换。

比如我们可以实现一个独立的数据导出服务,它能够自动的根据 API 返回的数据及对应的元数据导出成 Excel 文件,从而实现让导出与数据解藕,API 专心提供数据即可。

自动 SDK 生成

通过元数据信息,可以自动生成各个语言的 SDK 库,对于动态语言,甚至可以在运行时进行动态生成。