RestFul Api 設計 之 URL

全文來自阮一峰部落格文章

參考：

• 理解 RESTful 架構
• RESTful API 設計指南
• RESTful 實踐指南

1、動詞 + 賓語

RESTful 的核心思想就是，客戶端發出的資料操作指令都是"動詞 + 賓語"的結構。比如，GET /articles 這個命令，GET 是動詞，/articles 是賓語。
動詞通常就是五種 HTTP 方法，對應 CRUD 操作。

• GET：讀取（Read）
• POST：新建（Create）
• PUT：更新（Update）
• PATCH：更新（Update），通常是部分更新
• DELETE：刪除（Delete） 根據 HTTP 規範，動詞一律大寫。

2、動詞的覆蓋

有些客戶端只能使用 GET 和 POST 這兩種方法。伺服器必須接受 POST 模擬其他三個方法（PUT、PATCH、DELETE）。
這時，客戶端發出的 HTTP 請求，要加上 X-HTTP-Method-Override 屬性，告訴伺服器應該使用哪一個動詞，覆蓋 POST 方法。

POST /api/Person/4 HTTP/1.1

X-HTTP-Method-Override: PUT
上面程式碼中，X-HTTP-Method-Override 指定本次請求的方法是 PUT，而不是 POST。

3、賓語是名詞

賓語就是 API 的 URL，是 HTTP 動詞作用的物件。它應該是名詞，不能是動詞。比如，/articles 這個 URL 就是正確的，而下面的 URL 不是名詞，所以都是錯誤的。

• /getAllCars
• /createNewCar
• /deleteAllRedCars

4、複數 URL

既然 URL 是名詞，那麼應該使用複數，還是單數？
這沒有統一的規定，但是常見的操作是讀取一個集合，比如 GET /articles（讀取所有文章），這裡明顯應該是複數。
為了統一起見，建議都使用複數 URL，比如 GET /articles/2 要好於 GET /article/2

5、避免多級 URL

常見的情況是，資源需要多級分類，因此很容易寫出多級的 URL，比如獲取某個作者的某一類文章。
GET /authors/12/categories/2
這種 URL 不利於擴充套件，語義也不明確，往往要想一會，才能明白含義。
更好的做法是，除了第一級，其他級別都用查詢字串表達。
GET /authors/12?categories=2
下面是另一個例子，查詢已釋出的文章。你可能會設計成下面的 URL。
GET /articles/published
查詢字串的寫法明顯更好。
GET /articles?published=true

6、包含版本號的 URL 設計

一個設計誤區，就是在 URI 中加入版本號：

　　http://www.example.com/app/1.0/foo
　　http://www.example.com/app/1.1/foo
　　http://www.example.com/app/2.0/foo

因為不同的版本，可以理解成同一種資源的不同表現形式，所以應該採用同一個 URI。版本號可以在 HTTP 請求頭資訊的 Accept 欄位中進行區分（參見 Versioning REST Services）：

　　Accept: vnd.example-com.foo+json; version=1.0
　　Accept: vnd.example-com.foo+json; version=1.1
　　Accept: vnd.example-com.foo+json; version=2.0