站長資訊平臺

Web API 設計之最佳實踐

2018-07-20 來源：編程學習網(wǎng)

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

概述

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

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

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

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

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

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

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

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

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

API設計之目標

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

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

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

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

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

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

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

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

1 優(yōu)秀的API 文檔

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

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

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

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

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

2 穩(wěn)定與一致性

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

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

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

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

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

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

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

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

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

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

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

有時候?qū)嵲诓坏靡研枰薷模M量能夠最小差異的做改變。每次更新，我們可以記錄和發(fā)布 API 更新的文檔，告訴調(diào)用者 API的版本差異，詳細說明如何升級。

3 靈活性

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

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

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

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

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

4 安全性

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

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

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

比如在創(chuàng)建調(diào)用者用戶 ID 時生成一個 sha1 token ，存儲在數(shù)據(jù)庫里�？梢詫⒐� + Salt 的方式生成 token ，比如 username + 123456 ，然后再到數(shù)據(jù)庫查詢匹配用戶（篇幅原因，詳細可參閱本人拙著《 PHP 與 MySQL 高性能應用開發(fā)》，這里不再贅述）。

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

現(xiàn)在的時代，無論如何都得使用 SSL 。另外 OAuth 2.0 也已經(jīng)成為服務器端驗證的標準，大多數(shù)開發(fā)語言都有成熟的把持。

Web API大多需要支持 JavaScript 調(diào)用，如 JQuery 等庫來獲取數(shù)據(jù)。這時需要嚴格驗證來源，以保證非授權(quán)網(wǎng)站調(diào)用，防止用戶數(shù)據(jù)丟失或被竊取。

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

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

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

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

5 易用性

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

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

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

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

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

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

時至今日，已經(jīng)有很多不錯的工具能夠自動為生成 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 的庫，各種語言均有。當然我們要選擇成熟的，自己能夠控制好的項目。