翻譯:10 Best Practices for Better RESTful API
原文:https://medium.com/@mwaysolutions/10-best-practices-for-better-restful-api-cbe81b06f291
Web API 在最近幾年成為非常重要的主題,我們有著很多種不同的方法去設計我們後端的系統,因此如何去設計一個乾淨的API是非常重要的。
通常來說我們會採用RESTful為我們的Web Api的設計風格,而RESTful的概念是將API Endpoint的架構透過資源邏輯去切割,並用HTTP Methods去操作這些資源。
接下來說明一下十種用來實作乾淨RESTful API的設計風格。
一、使用名詞而非動詞
為了更好理解API的使用,請使用以下的結構去設計API的資源:

而不要是使用動詞:

個人心得:如果使用動詞的話,API的Endpoint會很複雜難懂且難以統一。
二、不應該使用GET method和query parameters來改變資源狀態
僅使用PUT、PATCH、POST和DELETE來改變資源的狀態,而不是使用GET。
錯誤示範如下:

個人心得:但如果是單純作query request的時候要用GET method,是因為GET能將使用者輸入的選擇條件保留在url中,能方便使用者將收尋結果儲存在我的最愛。
三、使用複數的名詞
不要加單數與複數名詞混雜著用,僅僅使用複數名詞來代表所有的資源。

個人心得:使用複數而不是單數的原因,我想是因為單數會讓人以為這個資源只有一個或者是唯一的,但其實大部分的資源都是複數個。
但文章留言中有人有給出不同的建議:
當資源之間有著多對一的關係時,一端的資源就能使用單數名詞來代表,也就是當A與B是多對一的關係時,API的Endpoint就會變成
/a_plural/a_id/b_singular
在Rails中routes.rb就會像是:
resources :a do
resource :b
end四、當資源之間有資料庫的關聯時使用子資源來表示
當資源屬於另一個資源例如多對多的關係時,使用子資源表示,例如:

在Rails中routes.rb就會像是:
resources :cars do
resources :drivers, shallow: true
end五、使用HTTP標頭來表示序列化的格式
client 跟 server 彼此在溝通時必須知道要使用什麼格式的資料,而這些格式必須被定義在HTTP的標頭。
Content-Type的標頭定義request的格式。
Accept的標頭定義response的格式。
六、使用HATEOAS
HATEOAS的全名為Hypermedia as The Engine of Application State,其原則為Hypermedia(也就是URL或稱超連結)應該拿來做為做為更好的嚮導去引導client使用API。

附上相關說明連結。
七、提供Filtering、Sorting、Field Selection和Paging來給使用者去獲取特定的資料
Filtering:
使用獨特的query parameter來去過濾並獲取特定範圍中的資料。

Sorting:
讓資源所有的屬性(attributes)都可以用升序或降序。

上述URL代表manufactorer降序,model升序。
Field selection:
有些情況下(例如手機平台上)只需要展示部分屬性(attributes)的資源,所以讓API使用者能去選擇要獲取那些屬性能提高系統彈性,還能降低網路流量加速API的使用。

Pagine:
使用limit和offset可以讓使用者彈性地操作資料庫中的資料,並獲取特定範圍,例如前五十筆資料就可以使用limit=50&offset=0,也能讓API不會一次傳送太大量的資料,降低網路流量。

上述URL可以獲取第11~第15筆資料。
如果要獲取所有的資料可以使用HTTP 的 X-Total-Count的標頭。
如果要做到分頁獲取部分資料的話可以用HTTP的Link標頭,來實作下一頁或上一頁。

八、給予API版本
給予API不同的版本,不要發布沒有版本的API,並使用簡單的順序數字不要使用小數點如2.5。
可以簡單在URL放上API的版本來讓client操作不同版本的API。

個人心得:關於API Versioning除了放在URL上還可以透過header實作,但實際的優缺點就需要另外探討了。
九、使用HTTP status codes來實作錯誤處理
與API實作系統時,很難去忽略錯誤處理,單純的回傳HTTP 500對於追蹤API狀態沒有太大的幫助。
所以必須對HTTP status codes有一定的了解並知道在什麼情況回傳這些代碼。
HTTP 有超過七十種status codes來描述不同的伺服器狀態,我們不用全都使用,以下列出大概十幾種常用的codes。

當錯誤發生除了status code以外還需要加上error payloads。
所有的例外都必須配上一個error payloads,也就是錯誤訊息,以下給一個錯誤訊息的範例。

十、允許 overriding HTTP Method
有一些proxies(代理伺服器)只有POST和GET兩個methods,為了讓這些受到限制proxies也能去跟RESTful API溝通,API需要一個方式去override HTTP method。
可以使用客製化的HTTP標頭,X-HTTP-Method-Override來override POST method。
原文:
https://medium.com/@mwaysolutions/10-best-practices-for-better-restful-api-cbe81b06f291
