初嘗RESTFul規(guī)范

RESTFul是一種HTTP API接口規(guī)范臭挽，只要滿足的RESTFul規(guī)范，即可稱為RESTFul API咬腕。

既然是接口欢峰，我們先來(lái)了解一下，他和傳統(tǒng)的API接口有何不同吧郎汪。

本文以盡量簡(jiǎn)單明了的文字來(lái)介紹赤赊、描述，只講核心內(nèi)容煞赢，僅供入門(mén)指引抛计。

1 與傳統(tǒng)API的區(qū)別

RESTFul世界中，一切皆抽象為資源（Resource）照筑。

用戶是資源吹截，文章是資源、評(píng)論是資源凝危，抽象一點(diǎn)的session波俄、token等均是資源。

下面例子蛾默，我們通過(guò)以下幾個(gè)常用的HTTP方法對(duì)資源（圖書(shū)）進(jìn)行操作懦铺。

RESTFul中：

傳統(tǒng)API中：

2 URL設(shè)計(jì)

RESTFul API規(guī)范很簡(jiǎn)單，關(guān)鍵只需滿足這一點(diǎn)支鸡。

動(dòng)詞（HTTP動(dòng)作） + 名詞（資源）

2.1 常用動(dòng)作

通常我們采用以下5種 HTTP方法（動(dòng)作）冬念。

• GET：查詢（Read）
• POST：增加（Create）
• PUT：更新（Update）
• PATCH：部分更新，不常用（Update）
• DELETE：刪除（Delete）

2.2 名詞盡量復(fù)數(shù)

名詞盡量采用復(fù)數(shù)（語(yǔ)義更明確牧挣，但并不強(qiáng)制）急前，舉個(gè)例子：

不難發(fā)現(xiàn)，復(fù)數(shù)形式語(yǔ)義更明確瀑构。

2.3 方法 & 過(guò)濾參數(shù)

方法應(yīng)當(dāng)以路徑（path）的方式傳遞：

示例：

• 獲取部門(mén)：GET /departments
• 獲取部門(mén)下的所有員工：GET /departments/{id}/employees
• 獲取部門(mén)下的某個(gè)員工：GET /departments/{id}/employees/{id}
• 文章點(diǎn)贊：PUT /articles/{id}/praise

過(guò)濾參數(shù)應(yīng)當(dāng)以查詢字符串（QueryString）的方式傳遞：

示例：

• 獲取第1頁(yè)裆针，每頁(yè)顯示10條：GET /books?page=1&per_page=10
• 獲取已經(jīng)發(fā)布的文章：GET /articles?published=true（或等于1也行）

何時(shí)使用方法，何時(shí)使用過(guò)濾參數(shù)？

區(qū)別：

• 方法：獲取后的數(shù)據(jù)結(jié)構(gòu)不同了世吨。
• 過(guò)濾參數(shù)：獲取后的數(shù)據(jù)結(jié)構(gòu)還是一樣的澡刹，只是數(shù)量減少了。

3 響應(yīng)請(qǐng)求

必須盡可能返回意義準(zhǔn)確的HTTP狀態(tài)碼耘婚，不要一味的返回200狀態(tài)碼像屋。

狀態(tài)碼主要分為5類(lèi)：

在RESTFul中通常我們只需要用到2XX、4XX边篮、5XX。

• 1XX：信息類(lèi)
• 2XX：成功類(lèi)
• 3XX：重定向
• 4XX：客戶端錯(cuò)誤
• 5XX：服務(wù)器錯(cuò)誤

有關(guān)狀態(tài)碼的詳細(xì)參考：HTTP狀態(tài)碼

常用HTTP狀態(tài)碼：

3.1 成功類(lèi)

對(duì)于成功類(lèi)，除了GET請(qǐng)求需要返回響應(yīng)體（數(shù)據(jù)）之外挠进，其他請(qǐng)求均可不返回響應(yīng)體色乾。

獲取文章：

返回200狀態(tài)碼，返回的數(shù)據(jù)不需要進(jìn)行多余的包裝领突。

GET /articles/1

HTTP/1.1 200 OK

{
    "title": "文章標(biāo)題",
    "content": "文章內(nèi)容"
}

增加文章：

返回201狀態(tài)碼暖璧，可選返回響應(yīng)體（創(chuàng)建后的對(duì)象）。

POST /articles

HTTP/1.1 201 Created

{
    "id": 1,
    "title": "文章標(biāo)題",
    "content": "文章內(nèi)容"
}

HTTP/1.1 201 Created

更新文章：

若返回響應(yīng)體（更新后的對(duì)象）則使用200狀態(tài)碼君旦，否則使用204狀態(tài)碼澎办。

PUT /articles/1

HTTP/1.1 200 OK

{
    "id": 1,
    "title": "文章標(biāo)題",
    "content": "文章內(nèi)容"
}

HTTP/1.1 204 No Content

刪除文章：

返回204狀態(tài)碼。

DELETE /articles/1

HTTP/1.1 204 No Content

3.2 錯(cuò)誤類(lèi)

建議為所有錯(cuò)誤的請(qǐng)求響應(yīng)體加上錯(cuò)誤代碼金砍、消息字段局蚀。

錯(cuò)誤代碼建議由HTTP狀態(tài)碼 + 自定義的錯(cuò)誤代碼組成。

例如：客戶端錯(cuò)誤狀態(tài)碼為400恕稠，賬號(hào)或密碼錯(cuò)誤代碼為01（自定義）琅绅，組成40001錯(cuò)誤代碼。

3.2.1 客戶端錯(cuò)誤

登錄失敹煳　：

POST /tokens/login

HTTP/1.1 400 Bad Request

{
    "error_code": 40001,
    "message": "用戶名或密碼錯(cuò)誤"
}

用戶名已被注冊(cè)：

POST /users

HTTP/1.1 400 Bad Request

{
    "error_code": 40002,
    "message": "用戶名已被注冊(cè)"
}

未登錄：

HTTP/1.1 401 Unauthorized

{
    "error_code": 40101,
    "message": "用戶未登錄"
}

權(quán)限不足：

HTTP/1.1 403 Forbidden

{
    "error_code": 40301,
    "message": "權(quán)限不足"
}

文章不存在或已被刪除：

HTTP/1.1 404 Not Found

{
    "error_code": 40401,
    "message": "文章不存在或已被刪除"
}

3.2.2 服務(wù)器錯(cuò)誤

HTTP/1.1 500 Internal Server Error

{
    "error_code": 50001,
    "message": "服務(wù)器內(nèi)部錯(cuò)誤千扶，請(qǐng)稍后再試或聯(lián)系管理員"
}