什麼是API文檔？--斯科特·馬文

有時候，軟件開發人員想要的是本身的軟件被其餘應用軟件所應用，而不是讓人來操做。API使各類應用軟件互相通訊成爲了可能。

從事API文檔寫做15年，我親眼見證了API產品的崛起。各個公司開始搭建平臺，但願別人接入平臺並使用平臺提供的API。API的發展意味着API文檔的增多，這對技術文檔工程師無疑是一件好事。 

在本文中，我會闡述什麼是API，API文檔應當包含什麼，該類型的AP文檔面向哪些讀者，以及如何在這個領域快速入門。

什麼是API？

有時候，軟件開發人員想要讓本身的軟件被其餘應用軟件所應用，而不是讓具體的人來使用。所以互動就是和其餘軟件之間的，而不是一我的，因此就須要達成一個約定的方式去互動。這種語言，和其內在的一系列規則就被稱做應用程序編程接口（API）。基本上，API使各類應用軟件互相通訊成爲了可能。

你的軟件與API之間的信息交換常常表現爲一個請求和一個迴應的形式。你的軟件用API發出一個請求，另外一個程序則經過API返回響應。

有的API被用來在產品和外來產品之間交換數據。若是你想與Google 或Twitter交互，你能夠參考他們的API來寫代碼，從而在你的產品和他們的產品之間進行數據交換。 

有的API被用來在一個公司內部或者一個產品之間進行內在數據交換。Windows和Android操做系統都有內嵌API，以便開發人員編寫出可讓系統中不一樣模塊互相通訊的子程序。

還有的API被用與內部以及外部的交流。亞馬遜網站服務中有40多個服務都有給任何人使用的API。亞馬遜開發人員也會本身使用這些API，使各類服務之間能夠互相通訊。

不論是被內部仍是外部使用，API都須要造成文檔，以確保產生通訊。

什麼是API文檔？

API根據語言和功能的不一樣而有多樣化地形式，可是它們都有一個共性：用戶發出一個請求，API（有時候）返回一個響應。技術文檔工程師的任務就是詳細描述請求包含什麼，請求的形式是什麼，以及返回的數據是什麼。

API文檔的結構雖然多種多樣，可是我認爲一份好的API文檔須要給讀者展現：
•操做的語法
•操做具體能夠幹什麼
•操做涉及哪些變量，包括系統設定值，有效值，以及數據類型--布爾值、字符串，等等
•操做的返回值是什麼
•操做可能會遇到的報錯信息
•請求和響應的舉例 

這些聽起來不少，可是全部優秀的代碼都包含這些內容。API文檔工程師須要作的就是去查看，詢問，以及像一個編輯同樣去識別和減小代碼裏沒有的內容。

就核心而言，API文檔細化了代碼裏面的內容：可用的命令，命令的做用，以及各個命令的變量。傳統來講，API文檔描述了一個操做以及如何發出一個請求。通常是由包含參數名稱及參數取值的表格和代碼樣例組成。一個功能一個API文檔，將全部文檔組合，就是一份API參考指南。很基礎，但頗有用。

可是針對那些不單是發出一個簡單請求的API文檔應當怎麼寫？大多數開發人員想知道API是如何把各個命令串到一塊兒，以及如何在輸入和輸出間互動。針對這一點，不少文檔工程師編寫了開發指南，包含API的常見使用場景案例和任務，以及代碼樣例。

另外一種形式的API文檔，叫作「用戶指南」，內容跟代碼不相關，傾向於解釋API的相關命令行界面或圖形用戶界面。「用戶指南」一般包含了用來輔助理解API的概念、安裝部署、配置任務、以及最佳範例。

若是文檔工程師想要下降API的使用難度——從根本上幫助任何一個有電腦的人使用API—他/她將會開發一個「快速入門指南」。這類文檔經過執行一系列任務引導用戶理解API，加深對API操做和後續任務的瞭解

一些公司會把上述各種API相關文檔打包，以軟件開發工具包（SDK）的形式發佈。使用SDK的人們一般但願裏面包含的不僅是API文檔。通暢狀況下SDK應當包括代碼，測試平臺和文檔。

基本上，API文檔的讀者都關注這兩個方面：正確的信息和可執行的代碼樣例。

誰會使用API文檔？

在技術溝通交流中，咱們常常會把讀者分爲三大類：終端用戶、系統管理員、開發人員。我開始相信，不管是哪一種文檔，每一個讀者都只是一個某種意義的終端用戶。一些終端用戶想要知道如何在應用中建立新文件。一些終端用戶想要知道如何在一個終端或命令提示運行一個命令。還有一些終端用戶想要知道如何開發和其餘程序交換數據的程序。

API文檔的終端用戶一般是開發人員，可是也有一些針對系統管理員的API文檔。系統管理員一般查看API文檔是爲了運行不須要編程的但必須在基礎應用上運行的任務。傳統來講，這是和命令行操做一塊兒的。好比，爲了在一個帳戶中建立一個用戶，系統管理員會執行一個命令來生成一個密匙，這樣用戶就能夠開始對API發出請求。 

另外一方面，開發人員，或許想建立一系列能夠在特定時間、特定場景下下以編程方式運行的操做。例如，當一個請求被返回，第二條命令會用第一條命令的返回值運行。在這種狀況下，開發人員就要建立一個使用API功能的工做流或框架。 

一些API是針對特殊命令，好比，「這一刻及時備份個人數據庫」。一些是以重複性和編程性的方式被使用，好比，「當個人網頁服務器達到80%忙碌時，建立另外一個網頁服務器，在兩個服務器中分擔負載」。

誰來編寫API文檔？

在這個日益發展的行業中寫做API文檔的人一般被稱做「程序文檔工程師」或者「高級技術文檔工程師」。一般有兩條路能夠成爲一名編寫API文檔的工程師。第一條路是指那些有很長時間寫做經驗，擅長溝通實踐，而且決定開始寫做API文檔的人。這一條路叫作「邊寫做邊學習代碼」。

第二條路是指那些決定致力於寫做的開發人員。這條路叫作「邊寫代碼邊學習寫做」。是一條邊開發邊學寫做的路。

本文針對走第一條路的探路者。若是你對API文檔寫做感興趣，遵循下面這幾條方法，你將受益不淺：
•學習讀懂代碼。意思是讀懂代碼，不是必須會寫。經過各類途徑查看閱讀代碼裏的註釋，嘗試理解代碼的含義。寫做API文檔須要對一種編程語言有基本瞭解，不必定要成爲一個開發人員。固然，你應當要知道看如何看代碼。大致上，你須要理解這個代碼是幹什麼、它爲何被開發、預期目的是什麼、以及誰會在什麼狀況下使用它。
•學習API技術常識。正常來講，API信息內容要麼用可擴展標示語言（XML），要麼用對象表示法（JSON），每個文件格式都比較容易理解。可是在仍然建議經過入門書去了解了解。當API經過表述性狀態轉移（REST），或是採用簡單對象訪問協議（SOAP）開發，你能夠經過一本好書或者Google搜索就能夠學到這些。
•查閱不一樣的API文檔。查看已有的老是好事，例如亞馬遜彈性計算雲文檔：(https://aws.amazon.com/documentation/ec2/)，谷歌雲存儲XML API：(https://developers.google.com/storage/docs/xml-api-overview)，還有Twitter的API文檔：(https://dev.twitter.com/docs/api)。
• 保持謙遜。向專家討教代碼疑問，最好的開發人員有時都會去向別人諮詢一些代碼上的疑問。若是他們都會如此，文檔工程師也不可能全都清楚。可是要記住了：必定要事先準備一下，不要由於本身沒有先調查清楚，浪費開發人員的時間。
•增加你的好奇心。若是API有工具包或者測試樁，試着用代碼玩一玩。使用API發出一個請求，看會發生什麼。

聽起來有好多工做要作，好多東西要學習，可是你只要開始，會發現也就小菜一碟。API文檔是一個正在發展的領域。建議你親自嘗試，看本身是否感興趣。咱們須要更多優秀的文檔工程師。

做者：泡芙小超人