你必須掌握的 RESTful 後端接口設計參考書

RESTful

RESTful 是 HTTP 協議的一種規則

HTTP服務可用端口最大爲 65535

HTTP URL

http://domain:addr/path?query#anchor

domain  # 域名地址
addr    # 端口:HTTP:80/HTTPS:443
path    # 資源路徑
query   # 資源篩選參數
anchor  # 錨點:頁面定位
複製代碼

RESTful API —— 設計要素

1.請求方法

| POST   | 提交 | 返回: 提交的信息
| GET    | 獲取 | 返回: 獲取到的數據
| PUT    | 替換 | 返回: 被替換的完整信息
| PATCH  | 更新 | 返回: 僅被更新的字段
| DELETE | 銷燬 | 返回: 204
複製代碼

2.資源路徑

http://api.example.com/v1/assets/id

http://      # 請求協議
api.         # API子域
example.com  # 域名
/v1          # API版本
/assets      # 資源路徑（複數）
/id          # 資源Id
複製代碼

3.過濾信息

• Query

基本格式: url?key=value
多個條件: url?key=value&key=value
分頁示範: url?page=2
複製代碼

4.狀態代碼

• 經常使用的響應狀態碼

200 —— OK                    // 成功返回
201 —— Created               // 成功建立
204 —— No Content            // 成功銷燬
400 —— Bad Request           // 語法錯誤
401 —— Unauthorized          // 沒有權限
403 —— Forbidden             // 請求被拒
404 —— Not Found             // 找不到資源
500 —— Internal Server Error // 內部服務器錯誤
501 —— Not Implemented       // 服務器沒法受理
複製代碼

5.返回響應信息

{
    "code": 200,
    "message": "",
    "body": ""
}
複製代碼

完整的 HTTP 狀態碼

響應: HTTP/1.1 200 OK

1xx（臨時響應）

100 —— Continue             // 繼續請求，服務器正在等待
101 —— Switching Protocol   // 服務器準備切換協議
103 —— // 一個新的狀態碼，能夠讓服務器在主標題以前儘早發送標題，這有助於預加載等優化
複製代碼

2xx（響應成功）

200 —— OK                   // 成功返回了資源
201 —— Created              // 成功建立了資源
202 —— Accepted             // 請求接受但未處理
203 —— Non-Authoritative Information // 返回資源未受權
204 —— No Content           // 成功銷燬了資源
205 —— Reset Content        // 重置內容，無任何資源返回
206 —— Partial Content      // 處理了部分請求
複製代碼

3xx（請求重定向）

300 —— Multiple Choice      // 選擇服務器提供的多種操做
301 —— Moved Permanently    // 永久移除，自動轉跳到新的資源
302 —— Found                // 自動轉跳到新的資源
303 —— See Other            // 查看資源位置
304 —— Not Modified         // 請求資源未修改
305 —— Use Proxy            // 須要代理
307 —— Temporary Redirect   // 臨時重定向
308 —— Permanent Redirect   // 永久重定向
複製代碼

4xx（請求錯誤）

400 —— Bad Request              // 請求字段語法錯誤
401 —— Unauthorized             // 請求未經受權
403 —— Forbidden                // 請求被服務器拒絕
404 —— Not Found                // 找不到資源
405 —— Method Not Allowed       // 請求方法不容許
406 —— Not Acceptable           // 請求不可接受
407 —— Proxy Authentication Required // 服務器代理須要受權
408 —— Request Timeout          // 請求超時
409 —— Conflict                 // 請求衝突
410 —— Gone                     // 請求的資源已銷燬
411 —— Length Required          // 指定有效內容長度標頭
412 —— Precondition Failed      // 請求條件沒法知足
413 —— Payload Too Large        // 請求體過大
414 —— URI Too Long             // 請求URL過長
415 —— Unsupported Media Type   // 請求的類型不支持
416 —— Requested Range Not Satisfiable // 請求的範圍不符合要求
417 —— Expectation Failed       // 服務器未知足請求標頭的要求
426 —— Upgrade Required         // 升級所需
428 —— Precondition Required    // 要求先決條件
429 —— Too Many Requests        // 太多的要求
431 —— Request Header Fields Too Large // 請求頭字段太大
451 —— Unavailable For Legal Reasons  // 因法律緣由不可用
複製代碼

5xx（服務器錯誤）

500 —— Internal Server Error        // 內部服務器錯誤
501 —— Not Implemented              // 服務器沒法受理
502 —— Bad Gateway                  // 服務器網關錯誤
503 —— Service Unavailable          // 服務器不可用
504 —— Gateway Timeout              // 服務器代理超時
505 —— HTTP Version Not Supported      // 不支持的HTTP版本
511 —— Network Authentication Required // 網絡認證要求
複製代碼