API設(shè)計(jì)并非易事，從設(shè)計(jì)到測試以至最終的發(fā)布需要經(jīng)歷一個(gè)漫長的過程，本文將主要探討Web API從設(shè)計(jì)到最終發(fā)布，開發(fā)者可能忽略或者應(yīng)該注意的事情，希望對你有所幫助。

當(dāng)設(shè)計(jì)、測試或發(fā)布一個(gè)新的Web API時(shí)，你是在一個(gè)原有的復(fù)雜系統(tǒng)上構(gòu)建新的系統(tǒng)。那么至少，你也要建立在HTTP上，而HTTP則是基于TCP/IP創(chuàng)建的、TCP/IP建立在一系列的管道上。當(dāng)然，你也需要考慮Web服務(wù)器、應(yīng)用程序框架或者是API框架。

API從設(shè)計(jì)到測試以至最終的發(fā)布需要經(jīng)歷一個(gè)漫長的過程，本文將主要探討Web API從設(shè)計(jì)到最終發(fā)布，開發(fā)者可能忽略或者應(yīng)該注意的東西。

HTTP篇

HTTP 1.1規(guī)范RFC2616是一個(gè)非常大的文檔，下面我們節(jié)選了一些可能會對API產(chǎn)生影響的內(nèi)容分享給大家：

1.Idempotent方法：GET、HEAD、PUT、DELETE、OPTIONS以及TRACE都屬于idempotent操作；也就是說，“the side-effects of N > 0 identical requests is the same as for a single request.” （RFC2616 §9.1.2）

2．驗(yàn)證：用戶訪問API需要進(jìn)行識別和驗(yàn)證，HTTP所提供的Authorization頭文件就是出于此目的（RFC2616 §14.8）。RFC2617則指定了具體的驗(yàn)證計(jì)劃，包括了最常見的HTTP基本驗(yàn)證。

3.201 Created：使用“201 Created”響應(yīng)代碼表示請求成功，并且創(chuàng)建了一個(gè)新資源。201響應(yīng)可以包含本地頭文件中的新資源URI。（RFC2616 §10.2.2）

4.202 Accepted：使用“202 Accepted”響應(yīng)代碼表示該請求是有效的，將會被處理，但還未完成。一般情況下是用在服務(wù)器后臺隊(duì)列可能出現(xiàn)的地方。（RFC2616 §10.2.3）

5.4XX和5XX狀態(tài)代碼：4XX狀態(tài)代碼與5XX狀態(tài)代碼有一個(gè)非常重要的區(qū)別：4XX代碼旨在表明客戶端錯(cuò)誤，而5XX則是表明服務(wù)端錯(cuò)誤。（RFC2616 §6.1.1）

6.410 Gone：“410 Gone”響應(yīng)代碼是一個(gè)很少使用的響應(yīng)式代碼，其主要是通知客戶端資源出現(xiàn)在URL中，但實(shí)際上并沒有。這個(gè)用在API里可以指明被刪除、存檔或過期的項(xiàng)目。（RFC2616 §10.4.11）

7.Expect:：100-continue：如果API客戶端打算發(fā)送一個(gè)大型的實(shí)體請求，像POST、PUT或PATCH，它可以發(fā)送“Expect: 100-continue”到HTTP頭文件里，在發(fā)送實(shí)體之前等待“100 continue”響應(yīng)。這就允許API在返回錯(cuò)誤響應(yīng)信息之前，可以驗(yàn)證那些合理的請求（例如401或者403）。使用它可以提高API的響應(yīng)能力以及在某些情景下減少寬帶。（RFC2616 §8.2.3）

8.保持連接暢通：與API服務(wù)器保持連接，對于多API請求是個(gè)非常大的性能提升。如果配置正確，每個(gè)Web服務(wù)器應(yīng)該支持keep-alive連接。

9.HTTP壓縮：HTTP壓縮可以同時(shí)用于響應(yīng)體（Accept-Encoding: gzip）和請求體（Content-Encoding: gzip），用來提升HTTP API的網(wǎng)絡(luò)性能。

10.HTTP緩存：在API響應(yīng)時(shí)提供一個(gè)Cache-Control頭文件。（RFC2616 §14.9）

11.緩存驗(yàn)證：如果你有緩存API，那么在響應(yīng)時(shí)，你應(yīng)該提供Last-Modified或Etag頭文件，然后支持IF-Modified-Since或者If-None-Match請求頭文件用于有條件的請求。這將允許客戶端檢查它們的緩存副本是否仍然有效，并且當(dāng)沒有請求時(shí)，阻止一個(gè)完整的資源下載。如果實(shí)現(xiàn)得當(dāng)，那么條件請求要比普通請求更有效。（RFC2616 §13.3）

12.條件修改：ETag頭文件也可以用于條件修改資源。（RFC2616 §14.24）

13.絕對重定向：這是一個(gè)鮮為人知的HTTP/1.1要求，重定向（如。201、301、302、303、307響應(yīng)代碼）應(yīng)該包含一個(gè)絕對URI本地響應(yīng)頭文件。許多客戶端在本地支持相對URI，但是如果你想讓API兼容更多客戶端，你應(yīng)該在重定向時(shí)使用絕對URI。（RFC2616 §14.30）

14.鏈接響應(yīng)頭文件：在RESTful API中，經(jīng)常需要提供轉(zhuǎn)向其他資源的鏈接，甚至響應(yīng)的內(nèi)容類型無法提供一種自然方式鏈接（例如，PDF或圖像）。RFC5988在響應(yīng)頭文件中指定了一個(gè)鏈接提供方法。

15.規(guī)范URL：對于多資源URL，RFC6596定義了統(tǒng)一的方法來規(guī)范網(wǎng)址鏈接。

16.塊傳輸編碼：如果響應(yīng)內(nèi)容太大，傳輸編碼：分塊（Chunked）是一種很好的流響應(yīng)到客戶端方式，它將會減少服務(wù)器和中間服務(wù)器的內(nèi)存使用需求（尤其是對實(shí)現(xiàn)HTTP壓縮），并且提供更快的首字節(jié)響應(yīng)。

17.塊傳輸編碼里的錯(cuò)誤處理：在實(shí)現(xiàn)塊傳輸編碼之前，弄清如何處理發(fā)生在中間請求時(shí)產(chǎn)生的錯(cuò)誤是非常重要的。一旦對響應(yīng)進(jìn)行流處理，就無法改變HTTP的狀態(tài)代碼。

18. X-HTTP-Method-Override：有些HTTP客戶端不支持任何GET和POST，但你可以通過POST開通其他HTTP方法，使用約定成俗的標(biāo)準(zhǔn)X-HTTP-Method-Overrider頭文件去定義“真正”的HTTP方法。

19.URL長度：如果API支持復(fù)雜或任意的過濾項(xiàng)作為GET參數(shù)，那么記住，無論是客戶端還是服務(wù)器端都可能會因?yàn)槌^2000字節(jié)的URL長度帶來兼容性問題。

API設(shè)計(jì)篇

20.無狀態(tài)：沒有人希望API能夠存儲狀態(tài)，即使是在你的應(yīng)用程序服務(wù)器端。保持應(yīng)用程序服務(wù)器狀態(tài)自由，可以做到很輕易和很輕松地?cái)U(kuò)展。

21.內(nèi)容協(xié)商：讓你的資源支持多種表現(xiàn)方式，你可以使用內(nèi)容協(xié)商（content negotiation，例如Accept頭文件），或者使用不同的URL（例如……?format=json），或者可以讓你的內(nèi)容協(xié)商重定向到具體的格式。

22.URI模板：URI模板是一個(gè)定義良好的機(jī)制，用來提供URI組合能力到客戶端，或者定義URL訪問終端用戶模式。

23.Design for Intent：不要僅通過API來暴露內(nèi)部業(yè)務(wù)對象，設(shè)計(jì)API語義意味著要與用戶案例相匹配。更好地介紹，你可以閱讀Darrel Miller寫的API Craft。

24.版本：理論上講，一個(gè)設(shè)計(jì)良好的API是無需創(chuàng)建兼容的。而對于實(shí)用主義者，它們會把版本放入到API的URL中（例如：a/v1/path），所以，除非是處在一個(gè)安全的網(wǎng)絡(luò)狀態(tài)下，否則API可能不會按照預(yù)期那樣工作。

25.授權(quán)：記住，當(dāng)設(shè)計(jì)API時(shí)，并不是所有的用戶都可以訪問里面的任何對象。

26.批量操作：發(fā)送較少的請求來獲取或修改更多的數(shù)據(jù)，最好的方法就是在你的API里使用批量操作。

27.標(biāo)記頁數(shù)：API中使用分頁服務(wù)主要有兩大目的：一個(gè)是減少不必要的數(shù)據(jù)傳送到客戶端；一個(gè)是減少應(yīng)用服務(wù)器端不必要的操作。

28.統(tǒng)一的字符編碼：在設(shè)計(jì)和測試API時(shí)，Web服務(wù)需要支持更多的英文字符。如果你在URL中把Unicode字節(jié)作為自然鍵使用，它將會非常有趣（例如：/users/jimbob/ becomes /users/??/）。

29.錯(cuò)誤日志：在設(shè)計(jì)API時(shí)，創(chuàng)建錯(cuò)誤日志也是非常重要的。實(shí)踐時(shí)最好創(chuàng)建兩種日志記錄，一個(gè)是服務(wù)器端，一個(gè)是客戶端。

內(nèi)容篇

30.內(nèi)容類型：關(guān)于內(nèi)容類型（Content Type）可以寫整本書，就個(gè)人而言，我比較喜歡重用他人開發(fā)的內(nèi)容類型，像Atom、Collection+JSON、JSON HAL或者XHTML。定義一套屬于自己的內(nèi)容類型會比你期望的更好。

31.HATEOAS：超媒體作為應(yīng)用程序狀態(tài)引擎是一個(gè)REST約束，簡單點(diǎn)說就是你的內(nèi)容應(yīng)該通知客戶端下面要做的事情，可以通過鏈接或表單來通知。

32.日期/時(shí)間：當(dāng)你在API里提供日期/時(shí)間值時(shí)，應(yīng)該使用一種格式，包括時(shí)區(qū)信息。RFC3339是ISO8601的一個(gè)子集，是最簡單的日期時(shí)間格式。

安全篇

33.SSL：無論你的API是否支持HTTP或HTTPS，你都應(yīng)該考慮HTTPS這種訪問方式，它的增長趨勢日益明顯。

34.跨站請求偽造（CSRF）：如果使用API的交互式用戶與普通用戶都使用相同的驗(yàn)證，那么你的API很有可能會遭受CSRF攻擊。

35.Throttling：如果一個(gè)API用戶的請求數(shù)超過了規(guī)定，那么你應(yīng)該提供一個(gè)帶Retry-After header的503響應(yīng)。

36.婉轉(zhuǎn)的拒絕服務(wù)：Throttling可以阻止你用最簡單的方式進(jìn)行攻擊，但這里還有其他更機(jī)智的攻擊方式。例如Slowloris、Billion laughs、ReDoS，它們都不會占用太多資源，但是它們可以讓你的API在瞬間耗盡所有資源。

客戶端

無論你是否給用戶提供測試代碼或者是SDK開發(fā)包，都應(yīng)該給他們提供一個(gè)客戶端，并且遵循下面這幾個(gè)步驟：

37.保持連接暢通：一些HTTP客戶端需要做一些額外的工作來保持連接持久，持久的連接對感知API性能有著非常重要的影響。

38.授權(quán)之前的401：HTTP的另一個(gè)怪癖是，它們會在解決一個(gè)授權(quán)問題之前發(fā)出“401 Unauthorized”響應(yīng)。這樣就會延長API的請求時(shí)間。

39.Expect: 100-continue：至少有一個(gè)API客戶端默認(rèn)使用“Expect: 100-continue”，如果它沒有接受“100 Continue”響應(yīng)，在3秒的超時(shí)后會繼續(xù)發(fā)送請求。如果API不支持“100 Continue”，或許會產(chǎn)生另一個(gè)性能缺陷，導(dǎo)致客戶端禁用。

其它

40.文檔：編寫API文檔是令人厭煩的，但是手寫的API文檔通常是最好的。編寫時(shí)一定要包含這些內(nèi)容：一些可運(yùn)行的代碼或者curl命令行，方便查閱。你也可以參考一些文檔工具，例如：apiary.io、Mashery I/O Docs、Swagger。

41.設(shè)計(jì)與客戶：不要在真空中設(shè)計(jì)API，要與客戶打交道或者一起來設(shè)計(jì)API，參考用戶用例。

42.反饋：在設(shè)計(jì)API時(shí)，應(yīng)提供一個(gè)通道供用戶進(jìn)行反饋，

43.自動化測試：API測試是最簡單的事情。它最好是自動化的，畢竟，需要好好利用它。

上面提供的這份列表有趣嗎？對你是否有幫助呢？歡迎與我們一起討論。

來自：Mathieu Fenniak