RESTful API規範

簡介

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 返回一個空文檔