簡介
rest是一種軟件架構風格，如果你們的接口是rest接口，那么就可被認為你們的的接口是restful的，英文名詞和形容詞的區別。
rest接口是圍繞“資源”展開的，利用HTTP的協議，其實rest本也可以和HTTP無關，但是現在大家普遍的使用rest都是依托於HTTP協議。HTTP 的url即資源。
RFC 3986定義了通用的URI語法：
1 |
URI = scheme “://” authority “/” path [ “?” query ][ “#” fragment ] |
- scheme: 指底層用的協議，如http、https、ftp
- host: 服務器的IP地址或者域名
- port: 端口，http中默認80
- path: 訪問資源的路徑，就是咱們各種web 框架中定義的route路由
- query: 為發送給服務器的參數
- fragment: 錨點，定位到頁面的資源，錨點為資源id
RESTful API設計
資源路徑
對於rest資源的定義，即URL的定義，是最重要的；想要設計出優雅的、易讀的rest 接口，其實還是聽不容易的。
URL中不能有動詞
在Restful架構中，每個網址代表的是一種資源，所以網址中不能有動詞，只能有名詞，動詞由HTTP的 get、post、put、delete 四種方法來表示。
URL結尾不應該包含斜杠“/”
這是作為URL路徑中處理中最重要的規則之一，正斜杠（/）不會增加語義值，且可能導致混淆。REST API不允許一個尾部的斜杠，不應該將它們包含在提供給客戶端的鏈接的結尾處。 許多Web組件和框架將平等對待以下兩個URI： http://api.canvas.com/shapes/ http://api.canvas.com/shapes
但是，實際上URI中的每個字符都會計入資源的唯一身份的識別中。
兩個不同的URI映射到兩個不同的資源。如果URI不同，那么資源也是如此，反之亦然。因此，REST API必須生成和傳遞精確的URI，不能容忍任何的客戶端嘗試不精確的資源定位。
有些API碰到這種情況，可能設計為讓客戶端重定向到相應沒有尾斜杠的URI（也有可能會返回301 - 用來資源重定向）。
正斜杠分隔符”/“必須用來指示層級關系
rul的路徑中的正斜杠“/“字符用於指示資源之間的層次關系。 例如： http://api.user.com/schools/grades/classes/boys - 學校中所有的男生
http://api.college.com/students/3248234/courses - 檢索id為3248234的學生學習的所有課程的清單。
應該使用連字符”-“來提高URL的可讀性，而不是使用下划線”_”
為了使URL容易讓人們理解，請使用連字符”-“字符來提高長路徑中名稱的可讀性。 一些文本查看器為了區分強調URI，常常會在URI下加上下划線。這樣下划線”_”字符可能被文本查看器中默認的下划線部分地遮蔽或完全隱藏。 為避免這種混淆，請使用連字符”-“而不是下划線
URL路徑中首選小寫字母
RFC 3986將URI定義為區分大小寫，但scheme 和 host components除外。
URL路徑名詞均為復數
為了保證url格式的一致性，建議使用復數形式。
RESTful API對資源的操作
對於rest api資源的操作，由HTTP動詞表示
CURD操作
- GET: 獲取資源
- POST： 新建資源
- PUT：在服務器更新資源（向客戶端提供改變后的所有資源）
- PATCH: 在服務器更新資源（向客戶端提供改變的屬性）
- DELETE：刪除資源
PATCH一般不用，用PUT
資源過濾
在獲取資源的時候，有可能需要獲取某些“過濾”后的資源，例如指定前10行數據
http://api.user.com/schools/grades/classes/boys?page=1&page-size=10
返回狀態碼推薦標准HTTP狀態碼
有很多服務器將返回狀態碼一直設為200，然后在返回body里面自定義一些狀態碼來表示服務器返回結果的狀態碼。由於rest api是直接使用的HTTP協議，所以它的狀態碼也要盡量使用HTTP協議的狀態碼。
- 200 OK 服務器返回用戶請求的數據，該操作是冪等的
- 201 CREATED 新建或者修改數據成功
- 204 NOT CONTENT 刪除數據成功
- 400 BAD REQUEST 用戶發出的請求有問題，該操作是冪等的
- 401 Unauthoried 表示用戶沒有認證，無法進行操作
- 403 Forbidden 用戶訪問是被禁止的
- 422 Unprocesable Entity 當創建一個對象時，發生一個驗證錯誤
- 500 INTERNAL SERVER ERROR 服務器內部錯誤，用戶將無法判斷發出的請求是否成功
- 503 Service Unavailable 服務不可用狀態，多半是因為服務器問題，例如CPU占用率大，等等
返回結果
- GET /collections 返回資源列表
- GET /collections/:id 返回單獨的資源
- POST /collections 返回新生成的資源對象
- PUT /collections/:id 返回完整的資源對象
- PATCH /collections/:id 返回被修改的屬性
- DELETE /collections/:id 返回一個空文檔