翻譯:10 Best Practices for Better RESTful API

徐銘佑
徐銘佑
Sep 6, 2018 · 7 min read

原文: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

    徐銘佑

    Written by

    徐銘佑

    初生之犢,很畏虎。希望大家對於我寫的東西能給予指點,並點出不正確的地方,讓小弟我能學到更多的東西。

    Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
    Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
    Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade