在API與微服務飛速發(fā)展的當今世界，如何在開發(fā)web或移動應用時、或者是對現(xiàn)有的系統(tǒng)進行集成時找到最合適的API，通常是一項乏味的任務。與之相對的是，許多API提供者為了讓他們所有的最有價值的、以API驅(qū)動的資源能夠為潛在的調(diào)用者所發(fā)現(xiàn)并方便地進行訪問而絞盡腦汁。截至2014年底，市場上所存在的API目錄也只有為數(shù)不多的幾個，API提供者能夠在此列出他們的API，而API調(diào)用者可以在此找到他們所需的API。雖然這種途徑目前已經(jīng)經(jīng)過了一段時間的應用，但它是專門為了人類而設計的，其它應用程序與系統(tǒng)無法通過這種途徑找到適合的API，并根據(jù)他們調(diào)用的API資源進行相應的決策，

APIs.json于2014年5月發(fā)布

在2014年5月， 作為一家API管理基礎(chǔ)設施提供者，3Scale與API Evangelist共同合作，推出了一種機器可讀的開放式API發(fā)現(xiàn)格式，名為APIs.json。APIs.json的目標是提供一種簡單而通用的格式，可用于對API以及API運營的支持性元素進行索引。APIs.json的工作方式類似于Sitemap XML的格式，但它的設計目的不是對網(wǎng)站進行索引，而是對各種API進行索引，并將索引結(jié)果上傳至一個眾所周知的地點，API的提供者可以將他們的API資源的索引發(fā)布在此。

APIs.json的設計目標是為API提供者一個簡單的方式以更新他們的API索引，同時也讓其它搜索引擎、目標與API服務提供者訪問本地索引，讓該領(lǐng)域中的API資源可被發(fā)現(xiàn)。

快速了解APIs.json

APIs.json的定義總是由一些基礎(chǔ)信息的描述開始，用以表示API的作者，并將描述信息放在文件的頭信息中，這為調(diào)用者提供了關(guān)于API作者的一些描述參數(shù)，包括名稱、描述、圖片、標簽、創(chuàng)建日期、最后修改日期、以及該APIs.json所發(fā)布的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。與頭信息中的參數(shù)相似，每個API都可以設置幾個參數(shù)，用以對每個API進行描述，包括名稱、描述、圖片、標簽、humanURL（用于讓開發(fā)者進行訪問，以了解該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的基本元數(shù)據(jù)集之后，properties集合讓提供者可以定義其它希望引用的url。比較常見的作法是在APIs.json的開頭部分定義四個屬性：X-documentation、X-signup、X-pricing和X-tos。當然，你可以定義任何一種希望在API中使用的屬性，但推薦的方式是先從這幾個最基本的構(gòu)建塊開始，因為每個API調(diào)用者都會查找這些信息。

APIs.json中最基本的構(gòu)建塊屬性

 ...
  "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如何進行索引的細節(jié)，不過在APIs.json格式中的其它部分也可以加入聯(lián)系方式、標簽以及對其它相關(guān)APIs.json文件的引用。APIs.json的設計方式是成功一種將元數(shù)據(jù)與API運營進行掛鉤的基本框架，同時作為一種高度可擴展的url類型格式，可以在必要時在其中加入任意的外部引用，用于完整地描述API運營的每一方面。

不僅是一種發(fā)現(xiàn)格式

如果你在一群技術(shù)專家當中提起API發(fā)現(xiàn)這個話題，他們會很快地指出現(xiàn)有的一些API發(fā)現(xiàn)的解決方案，這些方案中通常會包括在API設計生命周期的早期階段采用超媒體模式。作為這些現(xiàn)有的API發(fā)現(xiàn)方式的一種替代方案，APIs.json專注于對當前的、并且在不斷發(fā)展中的API進行索引，而不管它屬于超媒體、RESTful甚至是SOAP web service技術(shù)。在一個理想的世界中，API的設計者都應遵循設計原則的通用集，但現(xiàn)實是，我們所面對的是數(shù)以千計的“雪花狀”API描述，它們存在于幾乎每個在線業(yè)務部門的API中。

APIs.json不僅將API發(fā)現(xiàn)的人機對話形式擴展為多種不同的服務類型，并且已將功能延伸至API發(fā)現(xiàn)的技術(shù)之外。在多數(shù)現(xiàn)已發(fā)布的APIs.json文件中，它們首先提供了其API的一些通用的技術(shù)構(gòu)建塊，例如通過API Blueprint或Swagger等常見的API描述格式對API的表面進行描述。不僅如此，APIs.json文件還能夠提供各種重要的業(yè)務元素，例如對文檔、價格說明、API注冊或帳號管理的引用。此外，APIs.json還能夠用于記錄在API運營方面一些更政策性的內(nèi)容，例如頻率限制、認證細節(jié)、服務條款以及隱私協(xié)議等等。以上所有這些功能綜合在一起，再加上機器可讀的訪問功能，使得APIs.json索引成為API運營的技術(shù)、業(yè)務、以及政策構(gòu)建塊的入口。

自托管的發(fā)現(xiàn)能力

雖然APIs.json文件多數(shù)情況下只用于單一的域名中（作為一個本地的API索引存在），但APIs.json文件中所包括的API可以分布于任意數(shù)量的公開網(wǎng)站或私有網(wǎng)站。這也意味著由APIs.json驅(qū)動的集合不僅能夠為API提供索引，同時可以將它們聚合在一起，成為一個更有價值的集合，這種集成能力可用于交付特定并且定向的應用程序、設備以及系統(tǒng)集成功能。

(點擊放大圖像)

Fitbit為它的API設計了專門的APIs.json文件，而HP同樣通過Link Creation Studio設計了APIs.json，這種做法對于成熟的API平臺已很常見。這些APIs.json文件由各自的API所有者負責維護。而其它任何人，可能是一個API代理或是一個應用程序開發(fā)代理，都可以發(fā)布各自的第三方APIs.json文件，在其中聚合Fitbit的API以及Link Creation Studio的API，通過這種方式建立一個專用的API集合，可用于開發(fā)需要用到Fitbit數(shù)據(jù)的應用程序。不僅如此，它還能夠提供鏈接以及圖片管理資源，通過圖片水印與QR碼的方式，將各種不同的應用程序連接到真實的世界中。

APIs.json的工具

即使APIs.json是一種開放的格式，但如果沒有現(xiàn)成的工具能夠促成API的發(fā)現(xiàn)與探索，那么它對于API的提供者或調(diào)用者來說都是沒什么價值的。考慮到這一點，人們所開發(fā)的第一個由APIs.json驅(qū)動的開源搜索工具為API的發(fā)現(xiàn)帶來了一種不同的方式。這個工具本身就具備自己的API，并且將所有機器可讀的APIs.json文件聚合到一個單一的、可以被公眾所訪問的API搜索引擎，名為APIs.io。

(點擊放大圖像)

在2015年，又有幾家公司為其推出了一些相關(guān)特性：

1) 企業(yè)內(nèi)部的API搜索引擎

2) 支持Google Chrome與Firefox瀏覽器的插件

3) 基于IDE的集合

4) 電子表格控制臺與可連接性

這些特性都是基于APIs.json文件的。而這些特性只是對基于APIs.json開發(fā)的現(xiàn)有工具的快速了解，它們將輔助API提供者、調(diào)用者，以及它們的系統(tǒng)或應用程序，讓它們在這個不斷擴張的API世界中被發(fā)現(xiàn)，并且確實有許多API已經(jīng)被成功地發(fā)現(xiàn)了。

除了用于開放工具的開發(fā)之外，APIs.json的潛能在運行時也得到了充分的表現(xiàn)。它不僅能夠作為API搜索引擎、集成開發(fā)環(huán)境、或統(tǒng)一電子表格工具，也可以在任何一個應用程序中作為一個潛在的引擎，為可用的API終結(jié)點、認證細節(jié)、響應代碼、底層所用的數(shù)據(jù)模型、API的許可選項、頻率限制、價格，以及整個API集成中的任何一個重要方面提供重要的詳細信息。

通過APIs.json，應用程序就能夠基于API的價格、可靠性、許可、服務條款條目等條件選擇其底層的云存儲提供商，甚至可以基于相同的條件，做出與消息發(fā)送、圖片、視頻或集成其它API等方面的決策。

簡單而強大的設計

APIs.json被設計為一種簡單的、機器可讀的格式，可以發(fā)布至一個人們所熟知的地方，為一個或多個API制作詳細的索引。這些索引提供了非常有價值的元數(shù)據(jù)，能夠為在API搜索引擎、IDE、電子表格以及其它任何工具、應用程序、設備以及系統(tǒng)集成做出實時的決策。APIs.json格式最初的設計是用于API發(fā)現(xiàn)，但它有很大的潛力成為API經(jīng)濟方面的一個潛在的引擎。

(點擊放大圖像)

對于API發(fā)現(xiàn)這一任務，你很容易將它看作一種臨時性的體驗。一旦找到一個API，就可以完成你的任務了，API的發(fā)現(xiàn)過程就此結(jié)束。但是，在現(xiàn)實中，在我們所創(chuàng)造出的這個永不停歇的數(shù)字世界中，這個過程是一而再再而三地不斷發(fā)生的，我們將永遠不停地繼續(xù)尋找能夠滿足我們不斷發(fā)展的需求的API。

伴隨著這種API發(fā)現(xiàn)周期的出現(xiàn)，我們也需要更多的數(shù)據(jù)點，不僅是基于關(guān)鍵字的搜索，也不僅是SOAP或是REST、JSON或是XML風格的發(fā)現(xiàn)功能。我們將根據(jù)現(xiàn)實世界中的數(shù)據(jù)點進行API發(fā)現(xiàn)與應用方面的決策，它將對整合過程產(chǎn)生深遠的影響，這些數(shù)據(jù)點包括價格、許可、可用性、穩(wěn)定性、服務條款等等。我們極度渴望為這些API運營領(lǐng)域找到機器可讀的描述以及各種工具，幫助我們實時地找到合適的API，并指導我們恰當?shù)剡\用它。

APIs.json是一種仍在發(fā)展中的支持工具，可作為那些有價值的、機器可讀的數(shù)據(jù)點的基本框架，次世代的API發(fā)現(xiàn)工具將打通API的運營。不僅如此，從發(fā)現(xiàn)、設計到管理、測試以及監(jiān)控，它還能夠讓API在整個生命周期的每一階段都做到可訪問性。它為這個虛擬引擎描繪了一副藍圖，以驅(qū)動整個API經(jīng)濟的發(fā)展，而不再局限于技術(shù)領(lǐng)域。對于從2015開始建立的各個業(yè)務部門的API，它將以最恰當?shù)姆绞教幚硭鼈兊臉I(yè)務以及政策。

關(guān)于作者