Web API 設計之最佳實踐

許多文章講述API的開發，如REST，SOAP，Json等。本篇以實踐為中心，理論和實踐相結合，與各位開發者討論在API開發前的設計思維。讓你可以在開發之前，將這些事想清楚，相信會事半功倍。

概述

各位朋友，何謂 API ？想必你一定知道 APP ， APP 我們手機端的軟件應用，它是 Application 的簡寫。

本文中心思想主要講述 API的 設計。 API 是個甚？ API 是英文是 Application Programming Interface 的簡寫，中文是應用編程接口之意，用于對接兩個應用間的數據和消息，以及函數調用等。

APP 是面向最終用戶， API 是面向軟件開發者。

在單機時代，類似于系統與應用程序之間，會有開放的函數來交互，稱之為系統級別的 API ，比如 Windows 系統的稱為 Win32 API ， Linux 內核也有開放接口。這些 API 絕大多數由 C/C++ 來開發，編譯或封裝給應用開發者調用。

開源平臺因為已經將源代碼開放到了底。我們在使用 API 的時候，還能看到 API 和底層方法怎么寫的，可以根據自身需要重新編譯。比如 JDK 、 Python 、 PHP 的虛擬機，開發者引用內置函數，知道其然還知所以然。

移動互聯網時代，越來越多的設備和應用需要接入互聯網。它們需要一個標準的協議和規范，來與服務器交互。例如網站， APP ，微信公眾號， IPad 客戶端， iWatch 還有很多 VR 設備、物聯網應用等都需要與服務器間交互。

當然最普遍的是Web網站應用。因為要求上線速度快，人員能力等各種原因，好多是面條式的代碼，而使用 API ，能夠讓這種情況得到有效改觀——因為使用了統一的通訊接口。

由于是與服務器通訊，皆使用 HTTP 協議，我們不去談 RESTFful ，且將此類稱為 HTTP API 或 Web API 。

Web API 的報文協議， RPC 有幾類，比如最常見的 WebService ，此類為開放的 XML 或遠程方法。另外還有 Json 格式，還有如 protobuffer ， thirft 等協議效率會更高。

API設計之目標

下面我們開始著手設計 API （本文默認 API 為 Web API ）。 API 開發者，首先需要站得更高的視角，盡最大努力以用戶的視角來開始設計。

API 開發者往往是這樣的視角： 『這個服務需要做什么？』或『這個服務需要提供什么？』

而 API 使用者關注的則是：我怎樣才能使用這個 API ， API 怎么滿足我的需要？或者更準確的說，『我咋樣才能花費最少時間，很簡單的調用 ？』。歸根結底， API 得好用。

各位看，其實不同角色導致了兩種截然不同的思維。所以 ，要設計好一個 API ，前提是視角要從 API 設計者轉向 使用者。

我們要不斷地問自己，如果你是使用的人，會問哪些問題。與其思考 API 可以作些什么，不妨多考慮它可能需要的，然后專注于完成這些，盡可能讓 用戶調用方便。

說時容易做時難，實際上會出很多情況會出忽我們的意料 。 比如某個公司寫 SOA API 的工程師，使用 Thirft 也好還是使用其它協議，寫的方法和參數非常晦澀難懂（這里不抓圖了）。

為何出此？出問題的可能是設計的架構師，或者工程師自己。這種情況就違背了我們寫 API 的初衷，如果調用 API ，還不如存取數據庫方便，API是為了效率更高，而非顯得很高深。

有鑒于此，我們再一起聊一聊寫好 API 接口的幾個方面。

1 優秀的API 文檔

程序猿最煩的兩件事兒，第一件是別人要他給自己的代碼寫文檔，第二件是別人的程序沒有留下文檔。

寫 API 的應該不是一個程序員，或者不能把自己當程序員，我們要對自己自己很高的要求。你要有寫一篇 API 文檔，能夠幫助開發者快速入手。

不必寫特別長的文字，只需要干凈利索，函數說明，參數，返回值是啥就可以。 API 比程序更復雜，所以你寫的文檔是極具價值的。

其實有很多值得關注的優秀的 API 文檔之范例。比如看 Twilio ， Django 還有淘寶、天貓、 404 網站 Google 的開放平臺文檔。這些產品都提供了非常全的文檔，且清晰易用，更促進用戶認可，更增進產品的市場份額。

一篇好文檔的體現，使用者在 15 分鐘能夠明白整體的使用，包括要遵循的規約和基礎函數。如果使用者不能在這此時間內能夠整合調用，這意味站我們有更多的事兒要做。

2 穩定與一致性

有的網站 API ，他們經常修改和完全重寫它們 API 。無論它有多牛，或者我們多么尊重他們的文化。但卻不是站在開發人員友好的角度。

一個網站或應用要成功，不僅要對他的億萬用戶友好，還要對合作伙伴、開發者友好，這樣的公司會更偉大，更成功。

無論有沒有龐大的用戶群，API設計者 都不要輕易做修改。比如多版本運行，比如對老版本應用支持相當長的一段時間，甚至是幾年。

比如一個類似 http://21cto.com/api/widgets 的URL，它返回 JSON 格式的內容。表面上 URL沒變 ，但是我經常修改的 JSON結構 ，加字段或修改數組類型。這樣調用的人都要和重新和接口重新對接，原來的邏輯被打亂。哎呀，這樣怎能受得了。

因此，在做 API 設計時，我們做一些提前規劃。比如從一開始就明確地 URL 命名為一個版本號。例如：

http://21ctom.com/api/widgets?version= 1

http://21cto.com/api/widgets/v1

這樣一來，比如初版的應用仍然可以正常工作，新版本的產品之間不會影響。

除非你有很詳實的數據表明，老版已經無用戶，我們當然在某個時候逐步淘汰以前的版本。在還有用戶的時候，需要繼續維護，然后給用戶足夠的提示，并提供足夠好的過渡計劃。

好的 URL 方案將包括 URL 中的主要版本 . 。對輸出格式或支持的數據類型的任何更改都會導致新的主要版本出現故障 . 。一般來說，如果你所做的是在你的輸出中添加密鑰或節點，但要在安全的地方，任何時候輸出的變化，碰撞一個版本，一般都可以保持相同的版本。

另外，除了隨著時間的推移，保持 API 穩定性，比如 內部函數保持一致。 在 API 中處理好參數，盡量使用相同或共享的參數體系，如在整個 API 中使用相同的命名約定和數據返回。

有時候實在不得已需要修改，盡量能夠最小差異的做改變。每次更新，我們可以記錄和發布 API 更新的文檔，告訴調用者 API的 版本差異，詳細說明如何升級。

3 靈活性

靈活性，表示輸入靈活，輸出多樣，這尤其適用于開放平臺的 API 開發者。調用的開發者，有個人開發者，公司，有網站，有 APP ，還有各種應用軟件，客戶端平臺并不是一致的，有的可能還不支持 JSON ，不支持 OAuth 等。

所以在設計 API 時，要有一定的靈活性和格式寬容，對于你的輸入和輸出的限制這是很好的。

API 可以支持多種輸出，如 XML 、 JSON 、 YAML 等格式。但在 URL 請求是一致的，如 /api/v1/component 。也可以接受請求類似 application/json 的 HTTP 頭，或者支持 URL 的 GET 參數變量，如 ?version=json 等。

為了容錯，對參數可以忽略大小寫，讓調用者減輕不必要的挫折。輸入的參數也可以做到多種格式，比如 GET 和 POST 方法都支持，格式可以為變量，也可以是 json 和 XML 。

支持多數的標準的輸入輸出，可以最大化的讓 API 具備靈活性，不在是我們個人的技術偏好。

4 安全性

安全是 API 相當重要的任務。對于內容型的 API ，如果沒有私密的數據傳輸，當然可以不設置鑒權。但對于一些數據敏感的數據來說，需要對調用的用戶進行身份驗證鑒權。

對于大多數 API ，可以使用簡單的基于 token 的身份驗證。 token 是一個哈希分配給調用者，允許通過 POST 或 HTTP 請求。比如可以用 sha1 或 MD5 的哈希字符串給到調用者，也可以使用 DES 的方式，如： da39a3ee5e6b4b0d3255bfef95601890afd80709 ”。

一個安全的 token ，最好不只是一串標識符，不可逆當然是最好的。

比如在創建調用者用戶 ID 時生成一個 sha1 token ，存儲在數據庫里。可以將哈希 + Salt 的方式生成 token ，比如 username + 123456 ，然后再到數據庫查詢匹配用戶（篇幅原因，詳細可參閱本人拙著《 PHP 與 MySQL 高性能應用開發》，這里不再贅述）。

另一個使用廣泛的方法，可以采用 OAuth 2.0 + SSL 。

現在的時代，無論如何都得使用 SSL 。另外 OAuth 2.0 也已經成為服務器端驗證的標準，大多數開發語言都有成熟的把持。

Web API大多需要 支持 JavaScript 調用，如 JQuery 等庫來獲取數據。這時需要嚴格驗證來源，以保證非授權網站調用，防止用戶數據丟失或被竊取。

可以使用白名單或用戶角色處理。比如可以通過用戶分級來對限制數據的創建、讀取、更新和刪除等操作。比如只有授權用戶才可以調用諸如 /user/delete/id 。如果未經授權，返回錯誤消息，比如 406 響應。

另外，還要避免 API 受跨站請求偽造（ CSRF ）攻擊。一些 API 應用會有 session 或 cookie 認證，一定要注意 CSRF跨站 。比如有一個請求來查看用戶的詳細信息（如 account/card/view/152423 ），需要在代碼中檢查 ID=152423 是指經過授權訪問的資源。

為此， API 需要嚴密驗證輸入數據，包括數據完整性和數據精度，以保證所有來自用戶的輸入能夠精確解析。

可以對 API 請求的歷史進行日志記錄，包括次數，頻率，異常時及時報警。

5 易用性

上面說了好多規則，似乎說的挺嚴重。

其實做的時候考慮周全，做到倒也不難。在開篇時我提到過， API 文檔要做到能夠在 15 分鐘內能讓開發者明白咋用，不是為了文檔而文檔，而是一篇優秀的教程，這也同時說明 API 的簡單易用。

如果我們做的是內部應用的 API ，最重要的是不需要溝通，通過看文檔就能讓調用者完成開發，這是一個可以達到的目標。

再總結一些具體的建議，與大家一起學習探討。

• 保持簡單，不做花哨的身份驗證

不做自定義的 URL 規則，比如 SOAP 、 JSON 或 REST 等啥都用。采用主流技術，讓開發者學習 API ，而不是既得學習 API 還有我那二把刀的新技術。

時至今日，已經有很多不錯的工具能夠自動為生成 API 和 API Doc ，如 Thirft 、 Alpaca( https://github.com/pksunkara/alpacaThrift) ，后者支持 Java ， PHP ， Python ， Ruby 。 C++ ， Perl ， Haskell ， Erlang ， C # 、、 JavaScript 、 Node.js ， Smalltalk 等語言。

另外， github 上也有一些生成 API 和 DOC 的庫，各種語言均有。當然我們要選擇成熟的，自己能夠控制好的項目。

• 提供一流的技術支持

很多時候，技術支持是國內產品的一大障礙。（這里我要檢討一下， 21CTO 公眾號網站我們會及時更新和回復的 ^_^ ）

需要經常問自己的幾個問題：

1. 對于用戶提交的問題，我們如何處理和回復？

2. 對用戶來說，文檔足夠簡單好學嗎？

如果是開放平臺的 API ，在線客服， Bug 跟蹤，郵件支持是基本的選項。確保第一時間回答 bug ，并真正解決它。

小結

如今大量的網絡服務和 APP 應用，有很多難用的產品，主要的原因包括設計不佳，缺乏文檔，經常修改，穩定，錯誤解決慢等問題。

希望本文有助于各位設計的 API 干凈，規范和易用，同時也對自己一個提醒。

雖然事情有時不會那么完美，但是我們在開始就這樣做，并一直向好的方向努力。如同下棋，多看 5 步，多想幾圈，總比只盯眼前好。 你說對嗎？

 

 

來自：http://mp.weixin.qq.com/s/hOuex-oWxHypx-RzburkZQ