RESTful API風格

任何對外提供服務的應用都繞不開API的發佈，你的API多是這個樣子：

www.baidu.com/api/v1/getUsername?id=1
或者
www.baidu.com/app/index.php?r=info/user/getUsername&id=1

若是答案是YES，那麼用句很潮的話，咱們能夠說你的API很不RESTful。

API風格

首先要說，無論你的API屬於哪一種風格，只要可以知足工做須要，就足夠了。API格式並不存在絕對的標準，只存在不一樣的設計風格。

API設計包含兩部分：請求和響應。
請求包含：請求URL、請求方法、請求頭部信息等。
響應包含：響應體和響應頭部信息。

一個請求URL的組成：

https://www.baidu.com:443/app/index.php?r=info/user/getUsername&id=1#tag
# 請求方法：GET
# 請求協議：protocal: https
# 請求端口：port: 443
# 請求域名：host: www.baidu.com
# 請求路徑：pathname: /app/index.php
# 查詢字符串：search: r=info/user/getUsername&id=1
# 頁面書籤：hash: #tag

根據URL組成部分：請求方法、請求路徑和查詢字符串，咱們有幾種常見的API風格。好比當刪除id=1的做者編寫的類別爲2的全部文章時：

# 純請求路徑
GET www.baidu.com/articles/delete/authors/1/categories/2
# 一級使用路徑，二級之後使用查詢字符串
GET www.baidu.com/articles/delete/author/1?category=2
# 純查詢字符串
GET www.baidu.com/deleteArticles?author=1&category=2
# RESTful風格
DELETE www.baidu.com/articles?author=1&category=2

前面三種都是GET請求，主要的區別在於多個查詢條件時怎麼傳遞查詢字符串，有的經過使用解析路徑，有的經過解析傳參，有的二者混用。同時在描述API功能時，可使用article/delete，也可使用deleteArticles。

而第四種RESTful API最大的區別在於行爲動詞DELETE的位置，不在url裏，而在請求方法中。

RESTful設計風格

REST（Representational State Transfer 表現層狀態轉移）是一種軟件架構風格、設計風格，而不是標準。主要用於客戶端和服務端的API交互，它的優點在於更簡潔、清晰、可讀性強。

REST的主要特色是：

1. 客戶端和服務端是無狀態的，任意請求都包含了處理須要的全部信息，同時服務端的變動對客戶端是透明的。
2. 資源用URI（Universal Resource Identifier 通用資源標識）來表示，經過請求方法來指明操做類型：GET/POST/PUT/DELETE。

無狀態是最重要的特性，大部分的Client-Server，Brower-Server也都能很好的支持。第2點則是咱們須要去關注的。

REST URL

表現層狀態轉移（REST）是一個大的概念，也很差理解，個人理解就是在URL的定義上可以清楚的表示其請求含義。它的核心思路就是動詞+賓語：

DELETE www.baidu.com/api/v1/articles?author=1&category=2
# 動詞 DELETE，表示要進行的操做是刪除，即狀態轉移
# 賓語 articles，表示文章這種資源URI，推薦用複數，即表現層
# 定語 author=1&category=2，表示具體是什麼資源
# 版本 api/v1，這個可以幫助咱們更好的進行版本的升級，同時不影響原有的請求

咱們用articles來指明資源類型，用author=1&category=2來在肯定具體的資源，用GET/POST/PUT/DELETE來指明要進行的增刪改查操做。

這種風格相比於/api/deleteArticles，聲明的方法數量只有1/4，各個接口之間的風格也更加統一，調用起來更加清晰。

同時這種方法可以保證瀏覽器常規能訪問的到的GET請求對資源來講是安全的。好比別人給咱們發送了一個連接：/deleteArticle?id=1，咱們絕對不會但願隨便點擊一下就會跳轉到瀏覽器訪問，而後誤刪了這個資源。

響應狀態碼

除了請求URL有要求，在響應時也有一些要求。咱們知道狀態碼有：

• 1xx: 請求相關信息
• 2xx: 操做成功
• 3xx: 重定向
• 4xx: 客戶端錯誤
• 5xx: 服務端錯誤

全部的狀態碼 共有100多種，涵蓋了絕大多數常見的網絡場景，並且是網絡通用的定義規範和解釋，所以咱們應該儘量使用精確的狀態碼。

當前有一些不太恰當的作法是即使請求出錯，依然使用200狀態碼，轉而將錯誤信息包含在響應體中，或者響應使用純文本致使沒法和正常數據同樣標準化解析，如：

httpCode: 200
response: {
    status: 1,
    msg: '請求無權限'
}
# 或：
httpCode: 200
response: '請求無權限'

但咱們其實能夠用更精確的狀態碼403表明權限不足，因此合適的響應結果應該是：

# 異常時
httpCode: 403,
httpErrorMsg: '請求無權限'
# 正常時：
httpCode: 200,
response: {
    status: 0,
    msg: '',
    data: []
}

總結

RESTful是一種API設計風格，並非一種強制規範和標準，它的特色在於請求和響應都簡潔清晰，可讀性強。

咱們主要關注幾點：

1. 無狀態
2. 請求URL = 動做（GET/POST/PUT/DELETE）+ 資源
3. 響應使用精確的狀態碼和JSON格式數據

參考資料

1. RESTful API 最佳實踐: http://www.ruanyifeng.com/blo...
2. RESTful: https://baike.baidu.com/item/...
3. 怎樣用通俗的語言解釋REST，以及RESTful？: https://www.zhihu.com/questio...
4. Status Code Definitions: https://www.w3.org/Protocols/...