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

概述

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

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

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

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

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

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

當(dāng)然最普遍的是Web網(wǎng)站應(yīng)用。因?yàn)橐�求上線速度快，人員能力等各種原因，好多是面條式的代碼，而使用 API ，能夠讓這種情況得到有效改觀——因?yàn)槭褂昧私y(tǒng)一的通訊接口。

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

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

API設(shè)計(jì)之目標(biāo)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

無論有沒有龐大的用戶群，API設(shè)計(jì)者 都不要輕易做修改。比如多版本運(yùn)行，比如對老版本應(yīng)用支持相當(dāng)長的一段時(shí)間，甚至是幾年。

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

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

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

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

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

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

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

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

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

3 靈活性

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

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

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

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

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

4 安全性

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

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

一個(gè)安全的 token ，最好不只是一串標(biāo)識符，不可逆當(dāng)然是最好的。

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

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

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

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

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

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

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

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

5 易用性

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

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

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

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

• 保持簡單，不做花哨的身份驗(yàn)證

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

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

• 提供一流的技術(shù)支持

很多時(shí)候，技術(shù)支持是國內(nèi)產(chǎn)品的一大障礙。（這里我要檢討一下， 21CTO 公眾號網(wǎng)站我們會及時(shí)更新和回復(fù)的 ^_^ ）

需要經(jīng)常問自己的幾個(gè)問題：

1. 對于用戶提交的問題，我們?nèi)绾翁幚砗突貜?fù)？

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

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

小結(jié)

如今大量的網(wǎng)絡(luò)服務(wù)和 APP 應(yīng)用，有很多難用的產(chǎn)品，主要的原因包括設(shè)計(jì)不佳，缺乏文檔，經(jīng)常修改，穩(wěn)定，錯(cuò)誤解決慢等問題。

希望本文有助于各位設(shè)計(jì)的 API 干凈，規(guī)范和易用，同時(shí)也對自己一個(gè)提醒。

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

 

 

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

 

標(biāo)簽： Google linux Mysql ssl 安全 代碼 服務(wù)器 服務(wù)器端 互聯(lián)網(wǎng) 開發(fā)者 數(shù)據(jù)庫 網(wǎng)絡(luò) 移動(dòng)互聯(lián) 移動(dòng)互聯(lián)網(wǎng) 移動(dòng)互聯(lián)網(wǎng)時(shí)代

版權(quán)申明：本站文章部分自網(wǎng)絡(luò)，如有侵權(quán)，請聯(lián)系：west999com@outlook.com
特別注意：本站所有轉(zhuǎn)載文章言論不代表本站觀點(diǎn)！
本站所提供的圖片等素材，版權(quán)歸原作者所有，如需使用，請與原作者聯(lián)系。