在API与微服务飞速发展的当今世界，如何在开发web或移动应用时、或者是对现有的系统进行集成时找到最合适的API，通常是一项乏味的任务。与之相对的是，许多API提供者为了让他们所有的最有价值的、以API驱动的资源能够为潜在的调用者所发现并方便地进行访问而绞尽脑汁。截至2014年底，市场上所存在的API目录也只有为数不多的几个，API提供者能够在此列出他们的API，而API调用者可以在此找到他们所需的API。虽然这种途径目前已经经过了一段时间的应用，但它是专门为了人类而设计的，其它应用程序与系统无法通过这种途径找到适合的API，并根据他们调用的API资源进行相应的决策， [TOC] ## APIs.json于2014年5月发布 在2014年5月， 作为一家API管理基础设施提供者，3Scale与API Evangelist共同合作，推出了一种机器可读的开放式API发现格式，名为**APIs.json**。**APIs.json**的目标是提供一种简单而通用的格式，可用于对API以及API运营的支持性元素进行索引。**APIs.json**的工作方式类似于[Sitemap XML](http://www.sitemaps.org/protocol.html)的格式，但它的设计目的不是对网站进行索引，而是对各种API进行索引，并将索引结果上传至一个[众所周知的地点](https://tools.ietf.org/html/rfc5785)，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的设计者都应遵循设计原则的通用集，但现实是，我们所面对的是数以千计的“[雪花状](http://www.devx.com/blog/agile/avoid-integration-snowflakes-api-reuse.html)”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提供索引，同时可以将它们聚合在一起，成为一个更有价值的集合，这种集成能力可用于交付特定并且定向的应用程序、设备以及系统集成功能。 (点击放大图像) [](https://box.kancloud.cn/2015-09-12_55f43561d3422.png) Fitbit为[它的API](http://www.fitbit.com/apis.json)设计了专门的**APIs.json**文件，而HP同样通过[Link Creation Studio](https://s3-us-west-1.amazonaws.com/linkcreationstudio.com/developer/APIs.json)设计了**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](http://apis.io/)。 (点击放大图像) [](https://box.kancloud.cn/2015-09-12_55f4357096368.png) 在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的[价格](http://api-pricing.apievangelist.com/)、可靠性、[许可](http://apicommons.org/)、[服务条款条目](http://api-questions.apievangelist.com/)等条件选择其底层的云存储提供商，甚至可以基于相同的条件，做出与消息发送、图片、视频或集成其它API等方面的决策。 ### 简单而强大的设计 **APIs.json**被设计为一种简单的、机器可读的格式，可以发布至一个人们所熟知的地方，为一个或多个API制作详细的索引。这些索引提供了非常有价值的元数据，能够为在API搜索引擎、IDE、电子表格以及其它任何工具、应用程序、设备以及系统集成做出实时的决策。**APIs.json**格式最初的设计是用于API发现，但它有很大的潜力成为API经济方面的一个潜在的引擎。 (点击放大图像) [](https://box.kancloud.cn/2015-09-12_55f435723cfec.png) 对于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。 **查看英文原文：**[The APIs.json Discovery Format: Potential Engine in the API Economy](http://www.infoq.com/articles/apis-json-discovery-format)