restful 接口設計規範

1.URL中不能有動詞，隻能是名詞

說明: restful風格将應該遵循統一接口原則，把URL當成一種資源，通過HTTP方法來了解其含義。 是以URL中不能有動詞，而應該通過HTTP方法的GET/POST/PUT/DELETE方法來表示  查詢/新增/修改/删除

正例： GET  /zoos/animals

**反例：**GET   /zoos/getAnimals     /zoo/get_animals    /zoo/get-animals

2.URL結尾不應該包含斜杠“/”

說明：這是作為URL路徑中進行中最重要的規則之一，正斜杠（/）不會增加語義值，且可能導緻混淆。REST API不允許一個尾部的斜杠，不應該将它們包含在提供給用戶端的連結的結尾處。

正例： GET  /zoos/animals

反例： GET  /zoos/animals/

3.多個單詞應該使用"_"分開，不能使用駝峰命名，規避大小寫敏感的問題

4.URL路徑中首選小寫字母

5.RESTful API對資源的操作

• GET: 擷取資源
• POST： 建立資源
• PUT：在伺服器更新資源（向用戶端提供改變後的所有資源）
• PATCH: 一般不用，就使用PUT
• DELETE：删除資源

安全: 請求是否會給伺服器帶來副作用，即該操作用于擷取資訊而非修改資訊。如get是安全的，而post不安全

幂等: 不管進行多少次操作，結果都一樣。

GET和HEAD既安全又幂等，POST既不安全又不幂等，PUT和DELETE不安全但是幂等

6.使用(?)進行資源過濾

說明：擷取單個資源時，直接/後面跟資源ID，在擷取需要過濾的資源時，使用？來進行過濾

正例： GET  /zoos/animals/1     /zoos/animals?type=bird&id=1&color=green

反例： GET  /zoos/animals?id=1 

7.版本号

說明：可以在headers中自定義版本号，更一般的做法是在URL中說明版本号,github和oschina采用此做法

正例：/v1/users/1

反例：/users/1?version=v1    /users?version=v1&id=1

8.傳回狀态碼推薦标準HTTP狀态碼

• 1xx：相關資訊
• 2xx：操作成功。
• 3xX：重定向
• 4xx：用戶端錯誤
• 5xx：伺服器錯誤

9.對于狀态的修改，将狀态抽象為一個資源。

10.對于查詢參數很長的場景必須使用POST方法