在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)