在了解REST API URI設(shè)計(jì)的規(guī)則之前，讓我們快速瀏覽一些我們將要討論的術(shù)語(yǔ)。

URIs

REST API使用統(tǒng)一資源標(biāo)識(shí)符（URI）來(lái)尋址資源。在當(dāng)今互聯(lián)網(wǎng)上，充斥著各種各樣的URI設(shè)計(jì)規(guī)則，既有像//api.example.com/louvre/leonardo-da-vinci/mona-lisa這樣能夠清楚的傳達(dá)API資源模型的文章，也有很難理解的文章，例如：//api.example.com/68dd0-a9d3-11e0-9f1c-0800200c9a66 ；Tim Berners-Lee在他的“Axioms of Web Architecture”一文中將URI的不透明度總結(jié)成一句話：

唯一可以使用標(biāo)識(shí)符的是引用對(duì)象。在不取消引用時(shí)，就不應(yīng)該查看URI字符串的內(nèi)容以獲取其他信息。 
——蒂姆·伯納斯 - 李

客戶端必須遵循Web的鏈接范例，將URI視為不透明標(biāo)識(shí)符。

REST API設(shè)計(jì)人員應(yīng)該在考慮將REST API資源模型傳達(dá)給潛在的客戶端開(kāi)發(fā)者的前提下，創(chuàng)造URI。在這篇文章中，我將嘗試為REST API URI 引入一套設(shè)計(jì)規(guī)則。

先跳過(guò)規(guī)則，URI的通用語(yǔ)法也適用與本文中的URI。RFC 3986定義了通用URI語(yǔ)法，如下所示：

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

規(guī)則1：URI結(jié)尾不應(yīng)包含（/）

這是作為URI路徑中處理中最重要的規(guī)則之一，正斜杠（/）不會(huì)增加語(yǔ)義值，且可能導(dǎo)致混淆。REST API不允許一個(gè)尾部的斜杠，不應(yīng)該將它們包含在提供給客戶端的鏈接的結(jié)尾處。

許多Web組件和框架將平等對(duì)待以下兩個(gè)URI： 
http://api.canvas.com/shapes/ 
http://api.canvas.com/shapes

但是，實(shí)際上URI中的每個(gè)字符都會(huì)計(jì)入資源的唯一身份的識(shí)別中。

兩個(gè)不同的URI映射到兩個(gè)不同的資源。如果URI不同，那么資源也是如此，反之亦然。因此，REST API必須生成和傳遞精確的URI，不能容忍任何的客戶端嘗試不精確的資源定位。

有些API碰到這種情況，可能設(shè)計(jì)為讓客戶端重定向到相應(yīng)沒(méi)有尾斜杠的URI（也有可能會(huì)返回301 - 用來(lái)資源重定向）。

規(guī)則2：正斜杠分隔符（/）必須用來(lái)指示層級(jí)關(guān)系

URI的路徑中的正斜杠（/）字符用于指示資源之間的層次關(guān)系。

例如： 
(http://api.canvas.com/shapes/polygons/quadrilaterals/squares ；

規(guī)則3：應(yīng)使用連字符（ - ）來(lái)提高URI的可讀性

為了使您的URI容易讓人們理解，請(qǐng)使用連字符（ - ）字符來(lái)提高長(zhǎng)路徑中名稱的可讀性。在路徑中，應(yīng)該使用連字符代空格連接兩個(gè)單詞 。

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

規(guī)則4：不得在URI中使用下劃線（_）

一些文本查看器為了區(qū)分強(qiáng)調(diào)URI，常常會(huì)在URI下加上下劃線。這樣下劃線（_）字符可能被文本查看器中默認(rèn)的下劃線部分地遮蔽或完全隱藏。

為避免這種混淆，請(qǐng)使用連字符（ - ）而不是下劃線

規(guī)則5：URI路徑中首選小寫(xiě)字母

方便時(shí)，URI路徑中首選小寫(xiě)字母，因?yàn)榇髮?xiě)字母有時(shí)會(huì)導(dǎo)致一些問(wèn)題。RFC 3986將URI定義為區(qū)分大小寫(xiě)，但scheme 和 host components除外。

例如： 
http://api.example.com/my-folder/my-doc

HTTP://API.EXAMPLE.COM/my-folder/my-doc 
這個(gè)URI很好。URI格式規(guī)范（RFC 3986）認(rèn)為該URI與URI＃1相同。

http://api.example.com/My-Folder/my-doc 
而這個(gè)URI與URI 1和2不同，這可能會(huì)導(dǎo)致不必要的混淆。

規(guī)則6：文件擴(kuò)展名不應(yīng)包含在URI中

在Web上，（.）字符通常用于分隔URI的文件名和擴(kuò)展名。 
REST API不應(yīng)在URI中包含人造文件擴(kuò)展名，來(lái)指示郵件實(shí)體的格式。相反，他們應(yīng)該依賴通過(guò)Content-Type中的header傳遞media type，來(lái)確定如何處理正文的內(nèi)容。

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

如上所示：不應(yīng)使用文件擴(kuò)展名來(lái)表示格式。

應(yīng)鼓勵(lì)REST API客戶端使用HTTP提供的格式選擇機(jī)制Accept request header。

為了是鏈接和調(diào)試更簡(jiǎn)單，REST API應(yīng)該支持通過(guò)查詢參數(shù)來(lái)支持媒體類型的選擇。

規(guī)則7：端點(diǎn)名稱是單數(shù)還是復(fù)數(shù)？

keep-it-simple的原則在這里同樣適用。雖然一些”語(yǔ)法學(xué)家”會(huì)告訴你使用復(fù)數(shù)來(lái)描述資源的單個(gè)實(shí)例是錯(cuò)誤的，但實(shí)際上為了保持URI格式的一致性建議使用復(fù)數(shù)形式。

本著API提供商更容易實(shí)施和API使用者更容易操作的原則，可以不必糾結(jié)一些奇怪的復(fù)數(shù)（person/people，goose/geese）。

但是應(yīng)該怎么處理層級(jí)關(guān)系呢？如果一個(gè)關(guān)系只能存在于另一個(gè)資源中，RESTful原則就會(huì)提供有用的指導(dǎo)。我們來(lái)看一下這個(gè)例子。學(xué)生有一些課程。這些課程在邏輯上映射到學(xué)生終端，如下所示：

http://api.college.com/students/3248234/courses - 檢索id為3248234的學(xué)生學(xué)習(xí)的所有課程的清單。 
http://api.college.com/students/3248234/courses/physics -檢索該學(xué)生的物理課程

結(jié)論

當(dāng)你在設(shè)計(jì)REST API服務(wù)時(shí)，您必須注意這些由URI定義的資源。

正在構(gòu)建的服務(wù)中的每個(gè)資源將至少有一個(gè)URI標(biāo)識(shí)它。這個(gè)URI最好是有意義的，且能充分描述資源。URI應(yīng)遵循可預(yù)測(cè)的層次結(jié)構(gòu)，用來(lái)提高其可理解性，可用性：可預(yù)測(cè)的意義在于它們是一致的，它的層次結(jié)構(gòu)在數(shù)據(jù)關(guān)系上是有意義的。

RESTful API是為使用者編寫(xiě)的。URI的名稱和結(jié)構(gòu)應(yīng)該能夠向使用者傳達(dá)更清晰的含義。通過(guò)遵循上述規(guī)則，您將創(chuàng)建一個(gè)更清晰的的REST API與更友好的客戶端。這些并不是REST的規(guī)則或約束，僅僅是API的增強(qiáng)和補(bǔ)充。

我也建議你來(lái)看看http://blog.restcase.com/5-basic-rest-api-design-guidelines/這篇文章。

最后，望大家牢記：你在為你的客戶端設(shè)計(jì)API URI，而不僅僅是為你的數(shù)據(jù)。