[譯] REST API URI 設計的七準則

摘要：本文屬於原創，歡迎轉載，轉載請保留出處：https://github.com/jasonGeng88/blog

原文：http://blog.restcase.com/7-rules-for-rest-api-uri-design

在瞭解 REST API URI 設計的規則以前，讓咱們快速過一下咱們將要討論的一些術語。

URI

REST API 使用統一資源標識符（URI）來尋址資源。在今天的網站上，URI 設計範圍從能夠清楚地傳達API的資源模型，如：

http://api.example.com/louvre...

到那些難以讓人理解的，好比：

http://api.example.com/68dd0-...

Tim Berners-Lee 在他的「Web架構公理」列表中列出了關於 URI 的不透明度的註釋：

惟一可使用標識符的是對對象的引用。當你沒有取消引用時，你不該該查看 URI 字符串的內容以獲取其餘信息。- Tim Berners-Lee

客戶端必須遵循 Web 的連接範例，將 URI 視爲不透明標識符。

REST API 設計人員應該建立 URI，將 REST API 的資源模型傳達給潛在的客戶端開發人員。 在這篇文章中，我將嘗試爲 REST API URsI 引入一套設計規則。

在深刻了解規則以前，先看一下在 RFC 3986 中定義的通用 URI 語法，以下所示：

URI = scheme "://" authority "/" path ["?" query] ["#" fragment]

規則＃1：URI中不該包含尾隨的斜槓（/）

這是做爲 URI 路徑中最後一個字符的最重要的規則之一，正斜槓（/）不會增長語義值，並可能致使混淆。 REST API 不該該指望有一個尾部的斜槓，而且不該該將它們包含在它們提供給客戶端的連接中。

許多 Web 組件和框架將平等對待如下兩個 URI：

http://api.canvas.com/shapes/

http://api.canvas.com/shapes

然而，URI 中的每一個字符都會被計入做爲資源的惟一標識。

兩個不一樣的 URI 映射到兩個不一樣的資源。若是 URI 不一樣，那麼資源也會不一樣，反之亦然。所以，REST API 必須生成和傳達清晰的 URI，而且不該容忍任何客戶端嘗試去對一個資源進行模糊的標識。

更多的API可能會將客戶端重定向到末尾沒有斜槓的 URI 上，（他們也可能會返回 301 - 用於從新定位資源的 「Moved Permanently」）。

規則＃2：正斜槓分隔符（/）必須用於指示層次關係

在 URI 的路徑部分的正斜槓（/），用於表示資源之間的層次關係。

例如：

http://api.canvas.com/shapes/...

規則＃3：應使用連字符（ - ）來提升 URI 的可讀性

爲了使你的 URI 容易被人檢索和解釋，請使用連字符（ - ）來提升長路徑段中名稱的可讀性。在任何你將使用英文的空格或連字號的地方，在URI中都應該使用連字符來替換。

例如：

http://api.example.com/blogs/...

規則＃4：不得在 URI 中使用下劃線（_）

文本查看器（如瀏覽器，編輯器等）常常在 URI 下加下劃線，以提供可點擊的視覺提示。 根據應用程序的字體，下劃線（_）字符可能被這個下劃線部分地遮蔽或徹底隱藏。

爲避免這種混淆，請使用連字符（ - ）而不是下劃線

規則＃5：URI 路徑中首選小寫字母

方便的話，URI 路徑中首選小寫字母，由於大寫字母有時會致使問題。 RFC 3986 中將 URI 定義爲區分大小寫，但協議頭和域名除外。

例如：

http://api.example.com/my-fol...

HTTP://API.EXAMPLE.COM/my-fol...

在 URI 格式規範（RFC 3986）中這兩個 URI 是相同的。

http://api.example.com/My-Fol...

而這個 URI 與上面的兩個倒是不一樣的。

規則＃6：文件擴展名不該包含在 URI 中

在 Web 上，字符（.）一般用於分隔 URI 的文件名和擴展名。

一個 REST API 不該在 URI 中包含人造的文件擴展名，來表示消息實體的格式。 相反，他們應該經過 header 頭中 Content-Type 屬性的媒體類型來肯定如何處理實體的內容。

http://api.college.com/studen...

http://api.college.com/studen...

不該使用文件擴展名來表示格式偏好。

應鼓勵 REST API 客戶端使用 HTTP 提供的格式選擇機制，即請求 header 中的 Accept 屬性。

爲了實現簡單的連接和調試的便捷，REST API 也能夠經過查詢參數來支持媒體類型的選擇。

規則＃7：端點名稱是單數仍是複數？

這裏採用保持簡單的原則。雖然你的語法常識會告訴你使用複數來描述資源的單個實例是錯誤的，但實際的答案是保持 URI 格式一致而且始終使用複數形式。

沒必要處理奇怪的複數（person/people, goose/geese），這使 API 消費者的生活更美好，也使 API 提供商更容易實現（由於大多數現代框架將在一個通用的 controller 中處理 /students 和 /students/3248234）。

可是你怎麼處理關係呢？若是一個關係只能存在於另外一個資源中，RESTful 原則能夠提供有用的指導。咱們來看一下這個例子。某個學生有一些課程。這些課程在邏輯上映射到端點 /students，以下所示：

http://api.college.com/studen... - 檢索該學生所學習的全部課程清單，學生編號爲3248234。

http://api.college.com/studen... - 檢索該學生的物理課程，學生編號爲3248234。

結論

當你設計 REST API 服務時，你必須注意資源，這些資源由 URI 定義。

你正在構建的服務中的每一個資源，都將至少有一個 URI 來標識它。這個 URI 最好是有意義的，並能充分描述資源。URI 應遵循可預測的層次結構，以加強可理解性，從而提升可用性：可預測的意義在於它們是一致的，層次結構創建在數據具備結構關係的意義上。

RESTful API 是爲消費者編寫的。URI 的名稱和結構應該向消費者傳達意義。經過遵循上述規則，你將建立一個更加清晰的 REST API。 這不是一個 REST 規則或約束，而是加強了 API。

也建議你來看看這篇文章，http://blog.restcase.com/5-basic-rest-api-design-guidelines

爲你的客戶設計，而不是爲你的數據。