APIs.json 发现格式， API 经济的潜在引擎

本系列文章专注于 Web API__ 之 “元语言”的三个关键领域：即 API__ 描述、API__ 发现以及 API__ 档案。这些文章将涵盖所有这三个重要的趋势，并包括对这一快速发展的领域的一些关键人物的专访。

来自 InfoQ__ 的这篇文章是“描述、发现以及档案：进入Web API__ 的下一阶段”系列文章中的一篇，你可以在这里进行订阅，以便通过RSS__ 获取新文章的通知。

在API 与微服务飞速发展的当今世界，如何在开发web 或移动应用时、或者是对现有的系统进行集成时找到最合适的API，通常是一项乏味的任务。与之相对的是，许多API 提供者为了让他们所有的最有价值的、以API 驱动的资源能够为潜在的调用者所发现并方便地进行访问而绞尽脑汁。截至2014 年底，市场上所存在的API 目录也只有为数不多的几个，API 提供者能够在此列出他们的API，而API 调用者可以在此找到他们所需的API。虽然这种途径目前已经经过了一段时间的应用，但它是专门为了人类而设计的，其它应用程序与系统无法通过这种途径找到适合的API，并根据他们调用的API 资源进行相应的决策，

APIs.json 于 2014 年 5 月发布

在 2014 年 5 月， 作为一家 API 管理基础设施提供者，3Scale 与 API Evangelist 共同合作，推出了一种机器可读的开放式 API 发现格式，名为APIs.json。APIs.json的目标是提供一种简单而通用的格式，可用于对 API 以及 API 运营的支持性元素进行索引。APIs.json的工作方式类似于 Sitemap XML 的格式，但它的设计目的不是对网站进行索引，而是对各种 _API_ 进行索引，并将索引结果上传至一个众所周知的地点，API 的提供者可以将他们的API 资源的索引发布在此。

APIs.json 的设计目标是为 API 提供者一个简单的方式以更新他们的 API 索引，同时也让其它搜索引擎、目标与 API 服务提供者访问本地索引，让该领域中的 API 资源可被发现。

快速了解 APIs.json

APIs.json的定义总是由一些基础信息的描述开始，用以表示 API 的作者，并将描述信息放在文件的头信息中，这为调用者提供了关于 API 作者的一些描述参数，包括名称、描述、图片、标签、创建日期、最后修改日期、以及该APIs.json所发布的 url。

基本 APIs.json 指令集

 
{
 "name": "API Evangelist",
 "description": "This is an inventory of APIs available as part of the API Evangelist network.",
 "image": "https://s3.amazonaws.com/kinlane-productions/api-evangelist/t-shirts/KL_InApiWeTrust-1000.png",
 "tags": [
   "application programming interface",
   "API",
   "News",
   "Analysis"
 ],
 "created": "2014-04-07",
 "modified": "2014-07-09",
 "url": "http://apievangelist.com/*APIs.json*",
 "SpecificationVersion": "0.14",
 ...
}

接下来是APIs.json文件的核心部分，即 API 的集合。它让 API 提供者能够描述集合中的一个或多个 API。与头信息中的参数相似，每个 API 都可以设置几个参数，用以对每个 API 进行描述，包括名称、描述、图片、标签、humanURL（用于让开发者进行访问，以了解该 API 更多信息的 url 地址），以及 baseURL（机器将通过访问这个基本 url 以开始使用该 API）。

APIs.json 文件的核心 —— API 集合

 
...
 "apis": [
   {
     "name": "Analysis",
     "description": "Provides access to blog posts and analysis across the API Evangelist network.",
     "image": "https://s3.amazonaws.com/kinlane-productions/api-evangelist/t-shirts/KL_InApiWeTrust-1000.png",
     "humanURL": "http://developer.apievangelist.com",
     "baseURL": "http://api.apievangelist.com/definitions/Analysis",
     "tags": [
       "blog",
       "industry",
       "analysis",
       "new",
       "API",
       "Application Programming Interface"
     ],
     ...
   }
 ]
 ...

在定义了 API 的基本元数据集之后，properties 集合让提供者可以定义其它希望引用的 url。比较常见的作法是在APIs.json的开头部分定义四个属性：X-documentation、X-signup、X-pricing 和 X-tos。当然，你可以定义任何一种希望在 API 中使用的属性，但推荐的方式是先从这几个最基本的构建块开始，因为每个 API 调用者都会查找这些信息。

APIs.json 中最基本的构建块属性

 
...
 "properties": [
   {
     "type": "X-signup",
     "url": "https://apievangelist.3scale.net/"
   },
   {
     "type": "Swagger",
     "url": "http://api.apievangelist.com/definitions/Analysis"
   },
   {
     "type": "X-blog",
     "url": "http://developer.apievangelist.com/blog/"
   },
   {
     "type": "X-apicommonsmanifest",
     "url": "https://raw.githubusercontent.com/kinlane/analysis-api/master/api-commons-manifest.json"
   }
 ],
 ...

作为APIs.json集合的一部分，对它的整体描述将提供该 API 如何进行索引的细节，不过在APIs.json格式中的其它部分也可以加入联系方式、标签以及对其它相关APIs.json文件的引用。APIs.json的设计方式是成功一种将元数据与 API 运营进行挂钩的基本框架，同时作为一种高度可扩展的 url 类型格式，可以在必要时在其中加入任意的外部引用，用于完整地描述 API 运营的每一方面。

不仅是一种发现格式

如果你在一群技术专家当中提起 API 发现这个话题，他们会很快地指出现有的一些 API 发现的解决方案，这些方案中通常会包括在 API 设计生命周期的早期阶段采用超媒体模式。作为这些现有的 API 发现方式的一种替代方案，APIs.json专注于对当前的、并且在不断发展中的 API 进行索引，而不管它属于超媒体、RESTful 甚至是 SOAP web service 技术。在一个理想的世界中，API 的设计者都应遵循设计原则的通用集，但现实是，我们所面对的是数以千计的“雪花状”API 描述，它们存在于几乎每个在线业务部门的API 中。

APIs.json不仅将 API 发现的人机对话形式扩展为多种不同的服务类型，并且已将功能延伸至 API 发现的技术之外。在多数现已发布的APIs.json文件中，它们首先提供了其 API 的一些通用的技术构建块，例如通过 API Blueprint 或 Swagger 等常见的 API 描述格式对 API 的表面进行描述。不仅如此，APIs.json文件还能够提供各种重要的业务元素，例如对文档、价格说明、API 注册或帐号管理的引用。此外，APIs.json还能够用于记录在 API 运营方面一些更政策性的内容，例如频率限制、认证细节、服务条款以及隐私协议等等。以上所有这些功能综合在一起，再加上机器可读的访问功能，使得APIs.json索引成为 API 运营的技术、业务、以及政策构建块的入口。

自托管的发现能力

虽然APIs.json文件多数情况下只用于单一的域名中（作为一个本地的 API 索引存在），但 APIs.json 文件中所包括的 API 可以分布于任意数量的公开网站或私有网站。这也意味着由 APIs.json 驱动的集合不仅能够为 API 提供索引，同时可以将它们聚合在一起，成为一个更有价值的集合，这种集成能力可用于交付特定并且定向的应用程序、设备以及系统集成功能。

(点击放大图像)

Fitbit 为它的API 设计了专门的 APIs.json文件，而 HP 同样通过 Link Creation Studio 设计了APIs.json，这种做法对于成熟的 API 平台已很常见。这些APIs.json文件由各自的 API 所有者负责维护。而其它任何人，可能是一个 API 代理或是一个应用程序开发代理，都可以发布各自的第三方APIs.json文件，在其中聚合 Fitbit 的 API 以及 Link Creation Studio 的 API，通过这种方式建立一个专用的 API 集合，可用于开发需要用到 Fitbit 数据的应用程序。不仅如此，它还能够提供链接以及图片管理资源，通过图片水印与 QR 码的方式，将各种不同的应用程序连接到真实的世界中。

APIs.json 的工具

即使APIs.json是一种开放的格式，但如果没有现成的工具能够促成 API 的发现与探索，那么它对于 API 的提供者或调用者来说都是没什么价值的。考虑到这一点，人们所开发的第一个由APIs.json驱动的开源搜索工具为 API 的发现带来了一种不同的方式。这个工具本身就具备自己的 API，并且将所有机器可读的APIs.json文件聚合到一个单一的、可以被公众所访问的 API 搜索引擎，名为APIs.io 。

(点击放大图像)

在2015 年，又有几家公司为其推出了一些相关特性：

1) 企业内部的 API 搜索引擎

2) 支持 Google Chrome 与 Firefox 浏览器的插件

3) 基于 IDE 的集合

4) 电子表格控制台与可连接性

这些特性都是基于APIs.json文件的。而这些特性只是对基于APIs.json开发的现有工具的快速了解，它们将辅助 API 提供者、调用者，以及它们的系统或应用程序，让它们在这个不断扩张的 API 世界中被发现，并且确实有许多 API 已经被成功地发现了。

除了用于开放工具的开发之外，APIs.json的潜能在运行时也得到了充分的表现。它不仅能够作为 API 搜索引擎、集成开发环境、或统一电子表格工具，也可以在任何一个应用程序中作为一个潜在的引擎，为可用的 API 终结点、认证细节、响应代码、底层所用的数据模型、API 的许可选项、频率限制、价格，以及整个 API 集成中的任何一个重要方面提供重要的详细信息。

通过APIs.json，应用程序就能够基于 API 的价格、可靠性、许可、服务条款条目等条件选择其底层的云存储提供商，甚至可以基于相同的条件，做出与消息发送、图片、视频或集成其它API 等方面的决策。

简单而强大的设计

APIs.json被设计为一种简单的、机器可读的格式，可以发布至一个人们所熟知的地方，为一个或多个 API 制作详细的索引。这些索引提供了非常有价值的元数据，能够为在 API 搜索引擎、IDE、电子表格以及其它任何工具、应用程序、设备以及系统集成做出实时的决策。APIs.json格式最初的设计是用于 API 发现，但它有很大的潜力成为 API 经济方面的一个潜在的引擎。

(点击放大图像)

对于API 发现这一任务，你很容易将它看作一种临时性的体验。一旦找到一个API，就可以完成你的任务了，API 的发现过程就此结束。但是，在现实中，在我们所创造出的这个永不停歇的数字世界中，这个过程是一而再再而三地不断发生的，我们将永远不停地继续寻找能够满足我们不断发展的需求的API。

伴随着这种API 发现周期的出现，我们也需要更多的数据点，不仅是基于关键字的搜索，也不仅是SOAP 或是REST、JSON 或是XML 风格的发现功能。我们将根据现实世界中的数据点进行API 发现与应用方面的决策，它将对整合过程产生深远的影响，这些数据点包括价格、许可、可用性、稳定性、服务条款等等。我们极度渴望为这些API 运营领域找到机器可读的描述以及各种工具，帮助我们实时地找到合适的API，并指导我们恰当地运用它。

APIs.json是一种仍在发展中的支持工具，可作为那些有价值的、机器可读的数据点的基本框架，次世代的 API 发现工具将打通 API 的运营。不仅如此，从发现、设计到管理、测试以及监控，它还能够让 API 在整个生命周期的每一阶段都做到可访问性。它为这个虚拟引擎描绘了一副蓝图，以驱动整个 API 经济的发展，而不再局限于技术领域。对于从 2015 开始建立的各个业务部门的 API，它将以最恰当的方式处理它们的业务以及政策。

关于作者

Kin Lane 从上世纪 80 年代后期就开始进行数据库方面的工作，最近五年来则完全专注于应用程序编程接口，也就是人们所熟知的 API 方面的技术、业务与政策。Kin 的工作是让技术专家以及“普通人”了解数据的可移植性、互操作性、安全性以及隐私方面的重要性，其范围涵盖了个人以及公司所依赖的 web 以及移动应用平台。他的客户包括创业公司与一般企业，并且还作为一名前任的“总统创新之友”（Presidential Innovation Fellow）计划的成员为政府项目出谋划策。你可以关注他的博客 APIEvangelist.com，以及 Twitter 帐号 @kinlane。

本系列文章专注于 Web API__ 之 “元语言”的三个关键领域：即 API__ 描述、API__ 发现以及 API__ 档案。这些文章将涵盖所有这三个重要的趋势，并包括对这一快速发展的领域的一些关键人物的专访。

来自 InfoQ__ 的这篇文章是“描述、发现以及档案：进入Web API__ 的下一阶段”系列文章中的一篇，你可以在这里进行订阅，以便通过RSS__ 获取新文章的通知。

查看英文原文： The APIs.json Discovery Format: Potential Engine in the API Economy