REST API URI的七大設計原則

參考文章：rest api uri的七大設計原則

微服務restful 介面設計規範

rest設計規則

restful介面設計規範總結

rest風格url

http api設計規範-參考

在了解rest api uri設計的規則之前，讓我們快速瀏覽一些我們將要討論的術語。

rest api使用統一資源識別符號（uri）來定址資源。在當今網際網路上，充斥著各種各樣的uri設計規則，既有像這樣能夠清楚的傳達api資源模型的文章，也有很難理解的文章，例如：；

tim berners-lee在他的「axioms of web architecture」一文中將uri的不透明度總結成一句話：

唯一可以使用識別符號的是引用物件。在不取消引用時，就不應該檢視uri字串的內容以獲取其他資訊。

——蒂姆·伯納斯 - 李

客戶端必須遵循web的鏈結範例，將uri視為不透明識別符號。

rest api設計人員應該在考慮將rest api資源模型傳達給潛在的客戶端開發者的前提下，創造uri。在這篇文章中，我將嘗試為rest api uri引入一套設計規則。

先跳過規則，uri的通用語法也適用與本文中的uri。rfc 3986定義了通用uri語法，如下所示：

uri = scheme 「://」 authority 「/」 path [ 「?」 query ][ 「#」 fragment ]

這是作為uri路徑中處理中最重要的規則之一，正斜槓（/）不會增加語義值，且可能導致混淆。rest api不允許乙個尾部的斜槓，不應該將它們包含在提供給客戶端的鏈結的結尾處。

許多web元件和框架將平等對待以下兩個uri：

但是，實際上uri中的每個字元都會計入資源的唯一身份的識別中。

兩個不同的uri對映到兩個不同的資源。如果uri不同，那麼資源也是如此，反之亦然。因此，rest api必須生成和傳遞精確的uri，不能容忍任何的客戶端嘗試不精確的資源定位。

有些api碰到這種情況，可能設計為讓客戶端重定向到相應沒有尾斜槓的uri（也有可能會返回301- 用來資源重定向）。

uri的路徑中的正斜槓（/）字元用於指示資源之間的層次關係。

例如：(；

為了使您的uri容易讓人們理解，請使用連字元（-）字元來提高長路徑中名稱的可讀性。在路徑中，應該使用連字元代空格連線兩個單詞。

例如：

一些文字檢視器為了區分強調uri，常常會在uri下加上下劃線。這樣下劃線（_）字元可能被文字檢視器中預設的下劃線部分地遮蔽或完全隱藏。

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

方便時，uri路徑中首選小寫字母，因為大寫字母有時會導致一些問題。rfc 3986將uri定義為區分大小寫，但scheme和host components除外。

例如：這個uri很好。uri格式規範（rfc 3986）認為該uri與uri＃1相同。

而這個uri與uri 1和2不同，這可能會導致不必要的混淆。

在web上，（.）字元通常用於分隔uri的檔名和副檔名。

rest api不應在uri中包含人造副檔名，來指示郵件實體的格式。相反，他們應該依賴通過content-type中的header傳遞media type，來確定如何處理正文的內容。

如上所示：不應使用副檔名來表示格式。

應鼓勵rest api客戶端使用http提供的格式選擇機制accept request header。

為了是鏈結和除錯更簡單，rest api應該支援通過查詢引數來支援**型別的選擇。

keep-it-******的原則在這裡同樣適用。雖然一些」語法學家」會告訴你使用複數來描述資源的單個例項是錯誤的，但實際上為了保持uri格式的一致性建議使用複數形式。

本著api提供商更容易實施和api使用者更容易操作的原則，可以不必糾結一些奇怪的複數（person/people，goose/geese）。

但是應該怎麼處理層級關係呢？如果乙個關係只能存在於另乙個資源中，restful原則就會提供有用的指導。我們來看一下這個例子。學生有一些課程。這些課程在邏輯上對映到學生終端，如下所示：

-檢索id為3248234的學生學習的所有課程的清單。

/physics -檢索該學生的物理課程

當你在設計rest api服務時，您必須注意這些由uri定義的資源。

正在構建的服務中的每個資源將至少有乙個uri標識它。這個uri最好是有意義的，且能充分描述資源。uri應遵循可**的層次結構，用來提高其可理解性，可用性：可**的意義在於它們是一致的，它的層次結構在資料關係上是有意義的。

restful api是為使用者編寫的。uri的名稱和結構應該能夠向使用者傳達更清晰的含義。通過遵循上述規則，您將建立乙個更清晰的的rest api與更友好的客戶端。這些並不是rest的規則或約束，僅僅是api的增強和補充。

我也建議你來看看這篇文章。