REST API URI設計的7條規則

REST API URI設計的7條規則

這七個簡單的規則將幫助您編寫可讀的，無衝突的URI，以傳達全部必要的資源信息。

經過

蓋·萊文

在研究REST API URI設計的規則以前，讓咱們快速概述一下咱們將要討論的一些術語。

URIs

REST API使用統一資源標識符（URI）來尋址資源。在今天的網絡，URI設計範圍從明確傳達，如API的資源模型傑做http://api.example.com/louvre/leonardo-da-vinci/mona-lisa，
對那些更難爲人們所瞭解，如http://api.example.com/68dd0-a9d3-11e0-9f1c-0800200c9a66。

蒂姆·伯納斯·李（Tim Berners-Lee）在他的「 Web體系結構公理」列表中包括有關URI不透明的註釋：「惟一可使用標識符的是引用對象。當不進行解引用時，您不該查看URI字符串的內容以獲取其餘信息。」

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

REST API設計人員應建立URI，以將REST API的資源模型傳達給潛在的客戶端開發人員。在本文中，我將嘗試介紹REST APIURI的一組設計規則。

在深刻了解這些規則以前，本節介紹的有關URI格式的文字與URI的格式有關。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 –「永久移動」，用於從新定位資源」）。

規則2

必須使用正斜槓分隔符（/）表示層次關係。

URI的路徑部分使用正斜槓（/）字符表示資源之間的層次關係。例如：http://api.canvas.com/shapes/polygons/quadrilaterals/squares

規則3

應使用連字符（-）來提升URI的可讀性。

爲了使您的URI易於人們掃描和解釋，請使用連字符（-）來提升長路徑段中名稱的可讀性。在英語中使用空格或連字符的任何地方，都應在URI中使用連字符。

例如：http://api.example.com/blogs/guy-levin/posts/this-is-my-first-post

規則4

URI中不該使用下劃線（_）。

文本查看器應用程序（瀏覽器，編輯器等）一般在URI下劃線，以提供可單擊的可視提示。根據應用程序的字體，下劃線（_）字符可能會被此下劃線部分掩蓋或徹底隱藏。

爲避免這種混淆，請使用連字符（-）代替下劃線。

規則5

在URI路徑中應首選小寫字母。

方便時，URI路徑中最好使用小寫字母，由於大寫字母有時會引發問題。RFC 3986將URI定義爲區分大小寫，但方案和主機組件除外。

例如：

1）http://api.example.com/my-folder/my-doc

2）HTTP://API.EXAMPLE.COM/my-folder/my-doc 

上面的URI很好。URI格式規範（RFC 3986）認爲此URI與URI＃1相同。

3）http://api.example.com/My-Folder/my-doc

該URI與URI 1和URI 2不一樣，這可能致使沒必要要的混淆。

規則6

文件擴展名不該包含在URI中。

在Web上，句點（。）字符一般用於分隔URI的文件名和擴展名部分。REST API不該在URI中包含人工文件擴展名，以指示消息的實體主體的格式。相反，它們應該依靠經過Content-Type標頭傳達的媒體類型來肯定如何處理正文內容。

http://api.college.com/students/3248234/courses/2005/fall.json  
http://api.college.com/students/3248234/courses/2005/fall

文件擴展名不該用於指示格式首選項。

應該鼓勵REST API客戶端利用HTTP提供的格式選擇機制，即Accept request標頭。

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

規則7

端點名稱應爲單數仍是複數？

保持簡單規則在此處適用。儘管內部語法專家會告訴您使用複數形式描述資源的單個實例是錯誤的，但務實的答案是保持URI格式的一致性，並始終使用複數形式。

沒必要處理不規則複數形式（person/people, goose/geese），使API消費者的生活更美好，是對API提供商實現（如最現代化的框架經過 controller 處理 /students 和 /students/3248234 很容易）。

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

http://api.college.com/students/3248234/courses -檢索ID爲3248234的學生學習的全部課程的列表。
http://api.college.com/students/3248234/courses/physics -檢索ID爲3248234的學生的課程中的物理。

結論

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

您正在構建的一個或多個服務中的每一個資源將至少具備一個標識它的URI。最好是該URI有意義並充分描述資源。URI應該遵循可預測的層次結構，以加強易懂性，從而加強可用性：從統一性的意義上是可預測的，在數據​​具備結構關係的意義上則是分層的。

RESTful API是爲消費者編寫的。URI的名稱和結構應向這些使用者傳達含義。經過遵循上述規則，您將使用更快樂的客戶端來建立更簡潔的REST API。這不是REST規則或約束，可是它加強了API。

我還建議您看看這些準則。

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