APIs.json 發(fā)現(xiàn)格式， API經(jīng)濟(jì)的潛在引擎

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

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

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

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

快速了解APIs.json

APIs.json的定義總是由一些基礎(chǔ)信息的描述開始，用以表示API的作者，并將描述信息放在文件的頭信息中，這為調(diào)用者提供了關(guān)于API作者的一些描述參數(shù)，包括名稱、描述、圖片、標(biāo)簽、創(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提供者能夠描述集合中的一個(gè)或多個(gè)API。與頭信息中的參數(shù)相似，每個(gè)API都可以設(shè)置幾個(gè)參數(shù)，用以對每個(gè)API進(jìn)行描述，包括名稱、描述、圖片、標(biāo)簽、humanURL（用于讓開發(fā)者進(jìn)行訪問，以了解該API更多信息的url地址），以及baseURL（機(jī)器將通過訪問這個(gè)基本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的開頭部分定義四個(gè)屬性：X-documentation、X-signup、X-pricing和X-tos。當(dāng)然，你可以定義任何一種希望在API中使用的屬性，但推薦的方式是先從這幾個(gè)最基本的構(gòu)建塊開始，因?yàn)槊總€(gè)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如何進(jìn)行索引的細(xì)節(jié)，不過在APIs.json格式中的其它部分也可以加入聯(lián)系方式、標(biāo)簽以及對其它相關(guān)APIs.json文件的引用。APIs.json的設(shè)計(jì)方式是成功一種將元數(shù)據(jù)與API運(yùn)營進(jìn)行掛鉤的基本框架，同時(shí)作為一種高度可擴(kuò)展的url類型格式，可以在必要時(shí)在其中加入任意的外部引用，用于完整地描述API運(yùn)營的每一方面。

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

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

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

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

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

(點(diǎn)擊放大圖像)

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

APIs.json的工具

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

(點(diǎn)擊放大圖像)

在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)或應(yīng)用程序，讓它們在這個(gè)不斷擴(kuò)張的API世界中被發(fā)現(xiàn)，并且確實(shí)有許多API已經(jīng)被成功地發(fā)現(xiàn)了。

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

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

簡單而強(qiáng)大的設(shè)計(jì)

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

(點(diǎn)擊放大圖像)

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

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

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

關(guān)于作者