什麼是API？如何編寫和閱讀API文檔？

隨着API在互聯網時代中變得愈來愈廣泛，不只是編程人員會用到，如今也會要求產品經理或互聯網運營會調試和對接API。看這篇文章的你可能會使用或開發API，或者二者兼而有之。 所以，對你來講，不只要了解如何編寫，還要了解如何閱讀API文檔和測試。

什麼是API文檔？你也能夠將API文檔視爲雙方之間的服務協議。文檔概述了當第一方發送某種類型的請求時，第二方及其軟件將如何響應。這些類型的請求（稱爲API調用）在文檔中進行了描述，以便開發人員知道他們能夠用API作什麼以及如何進行操做。

優質的API文檔描述了它們的端點，解釋了爲何要使用它們，並提供了很是具體的示例來講明如何使用它們-全部這些方式對於初學者和高級用戶都是同樣清晰明瞭的。指示不明的API文檔過於技術性和基於文本描述，所以並不是全部用戶均可以正確使用它。

下面，咱們將經過七個步驟逐步介紹如何編寫優質的API文檔。

1. 瞭解用你API的用戶
2. 描繪你的用戶旅程
3. 從基礎功能陳述開始
4. 添加代碼示例
5. 列出您的狀態代碼和報錯消息
6. 用大白話來編寫和設計API文檔
7. 讓API文檔始終保持最新的狀態

1.瞭解用你API的用戶

與任何內容影響策略計劃或UI設計過程同樣，編寫API文檔的第一步是瞭解目標受衆。這須要瞭解您定位的用戶類型，內容須要爲他們提供的實用價值以及符合他們實際場景的方式。

在編寫API文檔時要記住兩個主要的用戶組。一組用戶是API文檔的直接使用者，所以他們只須要查看教程和代碼示例。該小組主要是開發人員。另一組用戶會評估API功能、價格、費率限制、安全性等等因素，以此瞭解該API如何與他們的業務需求和目標保持一致。該小組主要由CTO和產品經理以及一些開發人員組成。

你必須牢記這兩個角色，以確保文檔爲每一個讀者提供良好的體驗。

 

2.描繪你的用戶旅程

與任何產品同樣，API必須在買方旅程的每一個階段都提供內容。這意味着文檔應說明API能夠作什麼（或能夠解決什麼問題），其提供的功能和端點的多樣性以及與競爭對手的不一樣之處。

API文檔應回答的一些基本問題是：

1. 爲何要使用這個API？
2. 如何得到對不一樣工具和端點的訪問權限？
3. 得到權限後的下一步操做是什麼？
4. 如何使用某些特定功能？

3.從基礎功能陳述開始

每一個API和功能都是獨特或惟一的。好比說，有的API可將微博照片嵌入到電商平臺詳情頁中。有的API可以讓你經過B站旅行UP主訪問數千家推薦酒店。甚至還有的API，用於在網站上集成Yoda翻譯器。雖然每一個API的做用不同，可是每一個API文檔都應涵蓋一些基本知識。讓咱們在下面看一些例子。

• 身份驗證

因爲身份驗證對於保護API數據和開發人員及終端用戶的數據安全來講是很是重要的，所以API一般會有多種身份驗證方案，因此API文檔必須說明其每種身份驗證方法，以便用戶能夠得到受權和正確地使用API。例如，YouTube數據API支持兩種類型的受權憑證。其文檔說明了如何使用OAuth 2.0以及如何獲取API密鑰，以便用戶能夠選擇本身更熟悉的驗證方法。

• 速率限制

像用戶身份驗證同樣，速率限制能夠幫助防止傳輸意外或API濫用。 API速率限制是您能夠在給定時間內向API發送請求的次數。這些限制必須在API文檔中明確說明，以便用戶知道如何正確使用API及其功能。此信息最常在「使用條款」中找到。

• 使用條款

使用條款（或服務）是服務提供商與想要該服務的使用人之間的法律協議。後者必須贊成遵照這些條款才能使用該服務。在API文檔中，使用條款必須明肯定義API使用者在理想狀況下應如何使用API。這將有助於確保服務使用者充分利用API平臺和功能。

• 內容變動日誌

必須讓API使用者瞭解他們使用的API的任何貶低，這一點很重要。變動文檔能夠幫助他們正確地維護其應用程序，並充分利用API平臺的功能。案例：Twitter的API文檔具備一個更改日誌，其中記錄了對Twitter開發人員平臺所作的全部更改，包括新功能和新產品。

4.添加代碼示例

API文檔有兩個主要目標：使開發人員儘量容易地使用API，並使他們快速瞭解API的所有功能。實現這兩個目標的好方法是爲每一個API端點提供代碼示例。這樣，開發人員能夠了解端點的最關鍵功能，並從一些案例代碼開始着手，而後直接在案例代碼上調整參數以知足他們的實際需求和對接規範。

5.列出您的狀態代碼和錯誤消息

API文檔應明確概述用戶在進行API調用時可能指望的狀態代碼和錯誤消息。理想狀況下，每一個響應都應附有簡短說明，以便用戶瞭解什麼時候成功調用了API，什麼時候未成功調用，以及可以解決本身遇到的任何錯誤。一般，此信息放置在其本身的頁面上。這是快遞100API文檔中的示例。

6.用大白話來編寫和設計API文檔

若是你想要以一種易於用戶閱讀和瀏覽的方式編寫，構建和設計API文檔。這意味着根據用戶的使用場景和他們的需求來呈現和組織文檔的內容信息。用戶的使用場景是與用戶在哪裏，什麼時候，爲何以及如何尋找內容並與內容進行互動有關的全部內容。他們的需求還包括他們的目標，行爲和指望。

最好的API文檔是同時爲根本不熟悉該API的初學者和很是熟悉該API的開發人員而編寫的。這份文檔須要儘量地避免過多技術術語，並儘量提供了附加的文檔的上下文信息或內部連接。它還須要提供，如「入門」以及示例和教程，這些都是新手用戶須要的內容，而更高級的用戶則能夠跳過。

爲了確保用戶能夠選擇所需的內容，在設計API文檔時必須進行導航方式。最佳作法是使用標頭和側邊欄，以便用戶無需在頁面上上下滾動便可導航到文檔的另外一部分並提供搜索功能。其餘設計注意事項包括版式，配色方案和佈局。三列布局被認爲是帶有大量代碼示例的文檔的理想選擇。無襯線字體和對比鮮明的彩色連接也是不錯的設計選擇。

7.讓API文檔始終保持最新的狀態

爲了確保API使用者能夠得到最佳體驗和持續不斷地吸引新用戶，API提供者必須時常維護本身的API文檔。在過去，API文檔以PDF或靜態網頁的形式存在，這會讓文檔難以更新。如今，有一些工具能夠幫助您建立能夠自動更新的動態和交互式文檔。 Redocly和SwaggerUI是兩個比較常見的實際示例。

如何閱讀API文檔

若是你只是API使用者，而不是API服務提供者，那你就須要瞭解如何閱讀一份API文檔。儘管編寫和閱讀它的方法類似（尋找基本原理，嘗試代碼示例等），但它們並非徹底相同。讓咱們仔細看看如何閱讀一份API文檔，以瞭解使用特定API可能實現的功能。

• 從文檔概述開始

大多數API文檔將首先概述API的功能、如何鏈接API以及如何正確使用API。固然，你不須要了解概述的每一個細節部分，可是你應該大體瀏覽它一遍。

以快遞100的API文檔爲例子，首先快遞100的API文檔說明了快遞100的API用途，使用的協議和語言以及其身份驗證方案。在左側邊欄的「快速連接」部分，您將找到指向其使用指南和速率限制，測試賬戶，變動日誌以及開始使用API所需的全部其餘內容的重要連接。

• 深刻了解一種功能

瞭解API概述後，請瀏覽API參考文檔，其中列出了API的全部功能（也稱爲方法）。在這一點上，沒有必要完全閱讀或記住全部內容。相反，請仔細研究你特別感興趣的功能經過查看其參數和示例，你能夠了解是否能夠成功使用API來執行想要執行的確切操做。

例如，假設你想要經過快遞100的API實現如下的物流查詢功能：
- 在電商網頁/APP/小程序中，顧客在訂單詳情裏查看購買商品的物流地圖軌跡和物流軌跡文字信息一同展現給顧客

- 可視化訂單的在途狀態以及得到物流途徑城市的信息，監控快遞時效

- 預估包裹的到達時間，以及提示包裹還需多長時間到達，識別快遞狀態

- 發送提醒客戶簽收短信

在這種需求驅動下，你能夠導航到「接口文檔」 而後，查看其代碼語言、參數、響應和錯誤消息等等。

• 通讀API文檔教程

如今你已經知道是否可使用API來實現你要的需求了，請查看教程。因爲最好的API文檔應該能夠幫助用戶快速入門，所以大多數文檔都將包含用於完成任務的詳細教程。你應該通讀至少一篇教程，以瞭解哪些細節層次和示例是須要仔細學習的。

記錄API信息變動

隨着愈來愈多的公司提供API服務來造成高集成的用戶體驗，知道如何編寫和閱讀API文檔正變得愈來愈有價值。在建立或評估API文檔時，請確保你的API穩定易於閱讀和瀏覽，並清楚地將API的價值傳達給開發人員和非開發人員。 這樣能夠確保技術出身的用戶能夠開始快速和正確你的API，同事也要確保他們能夠與其餘人非技術出身的同事一塊兒使用。