在了解 REST API URI 設計的規則之前，讓我們快速過一下我們將要討論的一些術語，
URI
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 字串的內容以獲取其他資訊，- 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.xxx.com/shapes/
http://api.xxx.com/shapes
然而，URI 中的每個字符都會被計入作為資源的唯一標識，
兩個不同的 URI 映射到兩個不同的資源，如果 URI 不同，那么資源也會不同，反之亦然，
因此，REST API 必須生成和傳達清晰的 URI，并且不應容忍任何客戶端嘗試去對一個資源進行模糊的標識，
更多的API可能會將客戶端重定向到末尾沒有斜杠的 URI 上，（他們也可能會回傳 301 - 用于重新定位資源的 “Moved Permanently”），
規則＃2：正斜杠分隔符（/）必須用于指示層次關系
在 URI 的路徑部分的正斜杠（/），用于表示資源之間的層次關系，
例如：
http://api.xxx.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 定義為區分大小寫，但協議頭和域名除外，
例如：
http://api.example.com/my-folder/my-doc
HTTP://API.EXAMPLE.COM/my-folder/my-doc
在 URI 格式規范（RFC 3986）中這兩個 URI 是相同的，
http://api.example.com/My-Folder/my-doc
而這個 URI 與上面的兩個卻是不同的，
規則＃6：檔案擴展名不應包含在 URI 中
在 Web 上，字符（.）通常用于分隔 URI 的檔案名和擴展名，
一個 REST API 不應在 URI 中包含人造的檔案擴展名，來表示訊息物體的格式，相反，他們應該通過 header 頭中 Content-Type 屬性的媒體型別來確定如何處理物體的內容，
http://api.xxx.com/students/3248234/courses/2005/fall.json
http://api.xxx.com/students/3248234/courses/2005/fall
不應使用檔案擴展名來表示格式偏好，RESTful API設計技巧經驗總結，這篇也推薦看下，
應鼓勵 REST API 客戶端使用 HTTP 提供的格式選擇機制，即請求 header 中的 Accept 屬性，
為了實作簡單的鏈接和除錯的便捷，REST API 也可以通過查詢引數來支持媒體型別的選擇，
規則＃7：端點名稱是單數還是復數？
這里采用保持簡單的原則，雖然你的語法常識會告訴你使用復數來描述資源的單個實體是錯誤的，但實際的答案是保持 URI 格式一致并且始終使用復數形式，
不必處理奇怪的復數（person/people, goose/geese），這使 API 消費者的生活更美好，也使 API 提供商更容易實作（因為大多數現代框架將在一個通用的 controller 中處理 /students 和 /students/3248234），
但是你怎么處理關系呢？如果一個關系只能存在于另一個資源中，RESTful 原則可以提供有用的指導，我們來看一下這個例子，某個學生有一些課程，這些課程在邏輯上映射到端點 /students，如下所示：
檢索該學生所學習的所有課程清單，學生編號為3248234:
http://api.xxx.com/students/3248234/courses
檢索該學生的物理課程，學生編號為3248234:
http://api.xxx.com/students/3248234/courses/physics
結論
當你設計 REST API 服務時，你必須注意資源，這些資源由 URI 定義，
你正在構建的服務中的每個資源，都將至少有一個 URI 來標識它，這個 URI 最好是有意義的，并能充分描述資源，
URI 應遵循可預測的層次結構，以增強可理解性，從而提高可用性：可預測的意義在于它們是一致的，層次結構建立在資料具有結構關系的意義上，
RESTful API 是為消費者撰寫的，URI 的名稱和結構應該向消費者傳達意義，通過遵循上述規則，你將創建一個更加清晰的 REST API，這不是一個 REST 規則或約束，而是增強了 API，
為你的客戶設計，而不是為你的資料，
原文：blog.restcase.com/7-rules-for-rest-api-uri-design
譯文：https://github.com/jasonGeng88/blo
推薦去我的博客閱讀更多：
1.Java JVM、集合、多執行緒、新特性系列教程
2.Spring MVC、Spring Boot、Spring Cloud 系列教程
3.Maven、Git、Eclipse、Intellij IDEA 系列工具教程
4.Java、后端、架構、阿里巴巴等大廠最新面試題
覺得不錯，別忘了點贊+轉發哦！
轉載請註明出處，本文鏈接：https://www.uj5u.com/houduan/180693.html
標籤：Java