原文作者Mathieu Fenniak在博文中大呼：不要再設(shè)計(jì)易碎的Web API 了，否則你的合作伙伴或第三方開(kāi)發(fā)者會(huì)因此恨你，而離你遠(yuǎn)去的。他認(rèn)為，想設(shè)計(jì)出相對(duì)穩(wěn)定、牢固的API，關(guān)鍵在于以應(yīng)用目的為中心。文中還分享了設(shè)計(jì)優(yōu)秀API需要注意的幾點(diǎn)事項(xiàng)，我們一起來(lái)看下：

如果破壞了API，客戶(hù)會(huì)因此而恨你

很多Web API發(fā)布后，它就像被牢牢刻在石頭上無(wú)法做出兼容改變，這是個(gè)可怕的現(xiàn)象。倘若你破壞了API，你的客戶(hù)會(huì)因此而恨你，緊接著就是你的老板。因此，你必須對(duì)該API進(jìn)行更新、維護(hù)。

如果API設(shè)計(jì)的很好，那么它不會(huì)這么脆弱

減少其脆弱性或增加其韌性是管理API設(shè)計(jì)的方式之一，其關(guān)鍵在于以應(yīng)用目的為中心做設(shè)計(jì)。也就是SOA領(lǐng)域，所謂的面向業(yè)務(wù)（business-orientation）。也許這個(gè)概念很難理解，下面的這個(gè)示例能很好的說(shuō)明這一點(diǎn)：

URL之間的區(qū)別是什么呢？

http://api.fbi.gov/wanted?order_by=notoriety,desc&limit=10&page=1&fields=name,aka,known_associates,reward,description,last_seen

這是一份來(lái)自美國(guó)聯(lián)邦調(diào)查局的列表。該API包含了許多功能：你可以預(yù)定任何領(lǐng)域，按照升序或者降序進(jìn)行排列；可以指定結(jié)果計(jì)數(shù) ；可按頁(yè)查詢(xún)并且還根據(jù)指定詳細(xì)信息進(jìn)行檢索。

對(duì)比看下這個(gè)URL：

http://api.fbi.gov/wanted/most

兩個(gè)URL雖然有著相同的目標(biāo)，但是執(zhí)行方式不一樣。第一個(gè)是名程序員設(shè)計(jì)的，他能提供任何你想要的功能。設(shè)計(jì)中沒(méi)有描述用戶(hù)的意圖，但卻利用請(qǐng)求定義詳細(xì)信息來(lái)替代。

第二個(gè)URL意圖則非常明顯，顯示聯(lián)邦調(diào)查局頭號(hào)通緝犯名單，模糊的細(xì)節(jié)，這是根據(jù)意圖來(lái)進(jìn)行設(shè)計(jì)的。

根據(jù)”意圖“設(shè)計(jì)API，減少其脆弱性，有哪些優(yōu)勢(shì)呢？

1. 易使用——沒(méi)有復(fù)雜的程序、復(fù)雜的細(xì)節(jié)，易于學(xué)習(xí)；
2. 靈活性——意向驅(qū)動(dòng)API可隨著服務(wù)器端的變化而變化；
3. 一致性——一致性是API設(shè)計(jì)必備的一大特性；
4. 松耦合——這是向后兼容性問(wèn)題。你只需返回一個(gè)固定的值，后端兼容在意向驅(qū)動(dòng)API中會(huì)運(yùn)行的很好；
5. 可優(yōu)化——當(dāng)對(duì)數(shù)據(jù)庫(kù)進(jìn)行更新時(shí)，可計(jì)算優(yōu)化而不是在內(nèi)置的需求上，這比優(yōu)化每個(gè)組合的程序設(shè)計(jì)要困難得多；
6. 可緩存——易緩存。程序員的設(shè)計(jì)使得緩存困難（正?？刹樵?xún)參數(shù)）和無(wú)效（比如限制=5 / 10 / 15緩存未被命中）；
7. 易開(kāi)發(fā)—— 由于高復(fù)雜性使得開(kāi)發(fā)和測(cè)試測(cè)試程序員的 API變得更加困難和耗時(shí)。
8. 高效驗(yàn)證模型緩存 — — 快速檢查 If-None-Match/If-Modified-Since HTTP標(biāo)頭并作出"304 Not Modified"響應(yīng)。

但是，我需要一個(gè)更加通用的API設(shè)計(jì)……

為什么需要通用的API設(shè)計(jì)？這是因?yàn)橐庀驎?huì)讓你設(shè)計(jì)出更好的API。比如，API的靈活性。靈活的API非常有助于于開(kāi)發(fā)用戶(hù)界面，允許按字段排序、可自定義分頁(yè)、 排序和篩選或搜索。

此外，銘記UI意圖，還可以提供一個(gè)易于使用、開(kāi)發(fā)、靈活、一致、松耦合、可優(yōu)化、可緩存和高效的API的設(shè)計(jì)決策。

DRY原則（Don’t repeat yourself）

在執(zhí)行過(guò)程中不要使用重復(fù)原則，但在API設(shè)計(jì)中無(wú)須擔(dān)心重復(fù)設(shè)計(jì)。如果你提供了多個(gè)API端點(diǎn)可根據(jù)不同意向來(lái)檢索相似的對(duì)象，從常見(jiàn)的代碼路徑開(kāi)始吧。 為用戶(hù)提供更多具體的服務(wù)，你需要不斷對(duì)API進(jìn)行維護(hù)。

這個(gè)真的適用于現(xiàn)實(shí)的API領(lǐng)域嗎？

這是GitHub提交的一份Status API示例，通過(guò)持續(xù)集成服務(wù)來(lái)標(biāo)記存儲(chǔ)庫(kù)版本。

1. 定義特定的功能：指定一個(gè)國(guó)家修訂的版本庫(kù)
2. GitHub會(huì)自動(dòng)將請(qǐng)求相關(guān)聯(lián)的，顯示在一起
3. 無(wú)HTML 或可自定義的國(guó)家 ；API 有極少數(shù)量的數(shù)據(jù)需求。
4. 面向未來(lái)： 它以簡(jiǎn)約的方式滿(mǎn)足定義的問(wèn)題。
5. 狀態(tài)相關(guān)修訂 ；提交添加更多的請(qǐng)求工作。
6. GitHub 具有靈活性，可以進(jìn)行更改，而不會(huì)破壞兼容性：1. 對(duì)于API，GitHub暫不支持重寫(xiě)功能整個(gè)請(qǐng)求功能；2.可適用于其他UI領(lǐng)域；3. 如果 GitHub變成MercurialHub、SubversionHub、PerforceHub、 CvsHub、RcsHub，API可同樣被應(yīng)用。
7. GitHub靈活顯示提交狀態(tài)： 可在移動(dòng)應(yīng)用中顯示狀態(tài)、本地化的文本易合并。

還有個(gè)真實(shí)的例子 Twilio’s AvailablePhoneNumbers API，目的是為了搜索電話(huà)號(hào)碼分配到您的賬戶(hù)中，這個(gè)看起來(lái)就像典型的API集合，但是細(xì)節(jié)和意圖關(guān)聯(lián)并不大。

總結(jié)：

綜上所述，不再設(shè)計(jì)脆弱的Web API，我們得出幾點(diǎn)：1.根據(jù)自己的意向設(shè)計(jì)API；2. 在細(xì)節(jié)上是模糊的；3.提供多個(gè)API以區(qū)分用戶(hù)意向；4. 通過(guò)分享常見(jiàn)的實(shí)現(xiàn)方式而不是提供一個(gè)通用的服務(wù)來(lái)減少代碼重復(fù)。

英文出自： Mathieu.Fenniak