Restful 接口規范

[TOC]

01-02 Restful 接口規范

1.簡介

2000年Roy Fielding博士在其博士論文中提出REST(Representational State Transfer)風格的軟件架構模式后，REST就基本上迅速取代了復雜而笨重的SOAP，成為Web API的標准了。

RESTful作為目前最流行的API設計規范，是因為它：強大、簡潔、易上手。

2.URL設計

2.1數據的安全保障

• url鏈接一般都采用https協議進行傳輸
  • 采用https協議，可以提高數據交互過程中的安全性

2.2 接口特征表現

• 用api關鍵字標識接口url：
  • https://api.xxxx.com
  • https://www.xxxx.com/api
  • 看到api字眼，就代表該請求url鏈接是完成前后台數據交互的

2.3 多數據版本共存

• 在url鏈接中標識數據版本
  • https://api.xxxx.com/v1
  • https://api.xxxx.com/v2
  • url鏈接中的v1、v2就是不用數據版本的體現(只有在一種數據資源有多版本情況下)

2.4 數據即是資源

• 接口一般都是完成前后台數據的交互，交互的數據我們稱之為資源
  • https://api.xxxx.com/users
  • https://api.xxxx.com/books
  • https://api.xxxx.com/book
  • 一般提倡用資源的復數形式，在url鏈接中盡量不要出現操作資源的動詞，錯誤示范：https://api.xxxx.com/delete-user
• 特殊的接口可以出現動詞，因為這些接口一般沒有一個明確的資源，或動詞就是接口的核心內容
  • https://api.xxxx.com/login
  • https://api.xxxx.com/resgister

2.5 資源操作由請求方式決定

• 操作資源一般都會涉及到增刪改查，我們提供請求方式來標識增刪改查動作
  • https://api.xxxx.com/books - get請求：獲取所有書
  • https://api.xxxx.com/books/1 - get請求：獲取主鍵為1的書
  • https://api.xxxx.com/books - post請求：新增一本書
  • https://api.xxxx.com/books/1 - put請求：整體修改主鍵為1的書
  • https://api.xxxx.com/books/1 - pathc請求：局部修改主鍵為1的書
  • https://api.xxxx.com/books/1 - delete請求：刪除主鍵為1的書

3.響應狀態碼

3.1 正常響應

• 響應狀態碼2xx
  • 200：常規請求
  • 201：創建成功

3.2 重定向響應

• 響應狀態碼3xx
  • 301：永久重定向
  • 302：臨時重定向

3.3 客戶端異常

• 響應狀態碼4xx
  • 403：請求無權限
  • 404：請求路徑不存在
  • 405：請求方法不存在

3.4 服務器異常

• 響應狀態碼5xx
  • 500：服務器異常

4.響應結果

4.1 響應數據要有狀態碼、狀態信息以及數據本身

{
    "status": 0,
    "msg": "ok",
    "results": [
        {
            "name": "百年孤獨",
            "price": 33.60,
        },
        ...
    ]
}

4.2 需要url請求的資源

{
    "status": 0,
    "msg": "ok",
    "results": [
        {
            "name": "百年孤獨",
            "price": 33.60,
            "img": "https://image.xxxx.com/bngd.png"
        },
        ...
    ]
}