restful api的10個最佳實踐

Web API在過去的幾年裡非常盛行，因為它有着文法簡單、規範化和輕量級的優點，因為得到廣泛的推崇，很多過往的技術手段都慢慢轉換為使用Web API來開發。而Web API通常使用的設計方式是RESTful（Representational State Transfer，表述性狀态轉移），它使用了典型的HTTP方法，諸如GET、POST、PUT和DELETE來對資源進行管理和互動。

這裡列出設計RESTful API的10個最佳實踐。

1.在API中使用名詞，而不是動詞。

在RESTful中，API描述的應該是資源，而不是動作，是以在API應使用名詞去描述資源，而不是動詞用動詞去描述動作。

RESOURCE

GET:READ

POST:CREATE

PUT:UPDATE

DELTE:DELETE

/cars

傳回一個car的清單

建立一個新的car

更新car的資訊

删除所有的car

/cars/yanggb

傳回指定的car

Method not allowed(405)

更新指定的car的資訊

删除指定的car

而不是使用動詞，比如下面的API是不推薦的：

2.GET方法和查詢參數不應該改變資源狀态。

GET方法的API應該是幂等的，即不應該改變資源的狀态，無論請求多少次，傳回的結果都是一緻的。

如果要改變資源的狀态，應該使用POST、PUT和DELETE方法。

3.使用名詞的複數形式。

不要混合使用名詞的單數和複數形式，而應該為所有的資源從一開始就保持使用複數形式。

4.為關系使用子資源。

假如資源連接配接到其他資源，則應該使用子資源的形式來設計API。

5.使用HTTP頭決定序列化格式。

在用戶端和服務端都需要知道使用什麼格式來進行通信，這個格式應該在HTTP頭中指定。

Content-Type：定義請求的格式。

Accept：定義允許的響應格式的清單。

6.使用HATEOAS。

HATEOAS（Hypermedia as the Engine of Application State）是REST架構風格中最複雜的限制，也是建構成熟REST服務的核心。它是一個指導原則，規定超文本連結應該被用于在API中建立更好的資源導航。

在上面的傳回結果中，包含了超文本連結資源的資訊。

7.為集合提供過濾、排序、字段選擇和分頁。

過濾：為所有字段或者查詢語句提供獨立的查詢參數。

排序：允許跨越多字段的正序或者倒序排列。

字段選擇：隻列出需要的字段。一些情況下，隻需要在清單中查詢幾個有辨別意義的字段，并不需要從服務端把所有字段的值都請求出來，是以需要API支援選擇查詢字段的能力。這樣也可以在一定程度上提高網絡傳輸的性能與響應速度。

分頁：使用offset和limit來擷取固定數量的資源結果，當其中一個參數沒有出現時，應該提供各自的預設值，比如預設取第一頁，或者預設取20條資料。

8.版本化API。

確定強制實行API版本，并且不要釋出一個沒有版本的API。使用簡單的序列數字，比如v1，避免使用2.5.0這樣的形式（點分隔符）。

9.使用HTTP狀态碼處理錯誤。

忽略錯誤處理的API是很難使用的，簡單的傳回500和調用堆棧是非常不友好的，同時這些錯誤資訊在一定程度上來說也是無用的。

使用HTTP狀态碼

HTTP标準中提供了70多個狀态來描述傳回值，但是我們并不需要用到其中的全部，隻需要了解其中一些比較常用的就可以了。

使用error payloads

所有的請求異常都應該被映射到error payloads中。

10.允許重寫HTTP方法。

一些代理隻支援GET和POST方法。為了在這種限制下使用RESTful API（GET/POST/PUT/DELETE），則API需要重寫HTTP方法。

比如可以使用自定義的X-HTTP-Method-Override HTTP頭來重寫POST方法。

"感情實在是場無法掌控的事，沒有邏輯，沒有規律，更沒順理成章的必然。"

你要去做一個大人，不要回頭，不要難過。