APIs.json: 用于发布和发现 API 的工具

APIs.json 可以让网站将他们的 API 开放给搜索引擎，并且让 API 可被发现。

APIs.json 是一种 API 的定义格式，这种格式的文件可以用于向外界传达某个网站所提供的 API。该文件可以放在网站域名的根路径下，其中包含了一段关于 API 的机器可读的描述，以及一些指向其他同类文件的链接。APIs.json 与 robots.txt 有些类似，robots.txt 是一种被搜索引擎用来索引网站内容的文件，而 APIs.json 则被应用于 API 的发现和索引。

虽然 APIs.json 的版本目前还只是 0.14 版，但它的作者们认为它已经“准备就绪”，并且“社区可以真正地基于它构建起来”。该格式定义了大量强制和可选的元素，我们来对其中一部分作一下简介：

• Name [强制]: API 集合的名称，是供人类可读的字符串文本。
• Description [强制]:API 集合的描述，是供人类可读的文本。
• Created [强制]: 当前文件的创建时间。
• Apis (集合) [可选]: 文件中收录的 API 列表，每一条都包含以下元素： Name [强制]: API 的名称。
  Description [强制]: 供人类可读的关于 API 的描述。
  baseUrl: 与 API 的根 URL 或主要端点（primary endpoint）相对应的 Web URL。
  Version [可选]: 用于表示本描述所引用 API 的版本号的字符串。
  properties (集合):
  - type: 请查看保留关键字。
  - url 或值。

APIs.json 是 3Scale (Steve Willmott -@njyx 和 Nicolas Grenie -@picsoung) 和 API Evangelist (Kin Lane -@kinlane) 合作的成果。InfoQ 对 Kin Lane 进行了采访，从而对该项目的细节进行了进一步的了解。

InfoQ: 你们打算将 APIs.json 这种格式提交给某个标准化组织吗？

KL: 未来有可能会将 APIs.json 提交给标准化组织。但是目前，我们还是在努力工作以获得更多关于这种格式的反馈。希望通过在 1000 个以上的网站进行部署来使它更加的成熟，然后我们会再考虑下一步的计划。

InfoQ:有没有已经使用了这种格式的网站？

KL:最早使用该格式的站点是 apievangelist.com ，上面拥有来自 98 个独立提供者所提交的 138 个 API，但是其中很多都不是官方提供者所提交的。就是说它们大都是由第三方提交的。然而，该站点也有很多来自官方提供者的 APIs.json，这些提供者包括 Spotify、Diffbot、Paypal、MYOB 和 Neutrino API。

InfoQ: 既然你认为目前“社区可以真正地基于它构建起来”，那么为什么当前 APIs.json 的版本仍然只有 0.14。难道不应该是 1.0 版吗？

KL:我们从 0.11 版开始，根据反馈和经历的一些事情对它进行了快速地迭代开发，从而达到了 0.14 版。虽然它现在已经被广泛地使用起来，并且有数百个提供者认同了我们的工作，但将它视为 1.0 版目前看上去还不合适。我们已经花费了好几个月的时间来取得目前所拥有的成绩，但是我们仍然有很多的工作要做。

InfoQ:我了解到 APIs.json 已经支持了以下的一些 API 格式：Swagger、RAML、Blueprint、WADL 以及 WSDL。你们有计划在未来支持其他更多的格式吗？

KL: 我们从一开始就只专注于那些主流的 API 定义格式。然而，只要通过使用 API properties，你便可以指定任意你所选择的 API 定义格式。这里面并没有什么限制，但是一旦我们发现某些特定的格式获得了主流的使用，我们将会把它们囊括进核心的规范。

InfoQ:你们的短期计划和长远规划是怎样的？

KL:实现。实现。实现。我们正在向 API 提供者教授 APIs.json，并帮助他们进行实现。我们将会专注于帮助人们理解在内部以及公共发现方面使用 APIs.json 所带来的好处。沿着这个方向，我们会持续地打造一些有意义的工具，比如开源搜索引擎 APIs.io ，它可以帮助人们看到 APIs.json 所带来的好处。

与 APIs.json 相伴而生的便是 APIs.io ，这是一个开源的搜索引擎，它通过爬取网站来对它发现的 apis.json 文件进行索引。该网站同样也包含了一系列用于注册新 API 的工具，并且为它们生成并验证 apis.json 文件。

整个 APIs.json 项目基于 MIT 许可证发布，目前已在GitHub 上开源。

查看英文原文： APIs.json: Publishing and Discovering APIs