理解RESTful API
本博客采用創作共用版權協議, 要求署名、非商業用途和保持一致. 轉載本博客文章必須也遵循 署名-非商業用途-保持一致 的創作共用協議.
簡介
隨著Web開發的不斷開發, 低耦合的需求被提上了日程, 催生出了前后端分離的方案. 前后端分離使前端和服務器端相互獨立, 細化前后端開發, 于是近幾年API架構風行.
RESTful架構由 Roy Fielding 在一篇博士論文中提出. `REST, 即Representational State Transfer的縮寫, 中文可以譯為表現層狀態轉化
- 表現層 可以理解為資源的表現層, 資源 在網絡通信中無處不在, 一段文本, 一張圖片, 一個文檔都是資源, JSON是現在最常用的資源表示格式 . (相對于資源, 數據是一種更加抽象的形式)
- 狀態轉換 可以理解為客戶端發起的無狀態的HTTP請求, 導致服務器的資源的狀態轉變, 常用的五種HTTP動詞.
| HTTP動詞 | 語意 |
|---|---|
| GET | 從服務器端獲取資源(冪等) |
| POST | 在服務器新建資源 |
| PUT | 在服務器更新資源完整的資源(冪等) |
| PATCH | 在服務器更新部分資源 |
| DELETE | 從服務器刪除資源(冪等) |
冪等 : 在相同的數據和參數下，執行一次或多次產生的效果（副作用）是一樣的
設計
- 只提供json作為返回格式
Content-Type:application/json; charset=utf-8
- 資源 表示一種實體, 所以API設計時應該使用名詞, 動詞應該方法放在HTTP協議中
# GOOD /api/member/(\d+)/status GET: 從服務器換取用戶狀態 PATCH: 在服務器端更新用戶狀態 # BAD /api/show/(\d+)/status # GOOD /api/message?from=1&to=2 # BAD /api/message/(\d+)/to/(\d+) # 獲取某用戶下的所有gist GET /users/:username/gists # 創建一個新的gist POST /gists # 刪除某個特定的gist DELETE /gists/:id # star某個gist PUT /gists/:id/star # 搜索, 參數q, sort, order GET /search/repositories
# 獲取用戶資料 GET /api/member/(\d+)/info # 解禁用戶 DELETE /api/member/(\d+)/status #禁言用戶 PATCH /api/member/(\d+)/status # 獲取用戶所有私信 GET /api/member/(\d+)/messages # 獲取所有用戶的狀態 GET /api/members/status
- 使用復數表示多個資源
# GOOD /api/members/status # BAD /api/account
- 過濾信息
# filtering GET /api/members?client_id=1 # Sorting GET /api/members?sortby=created?=desc # pagination GET /api/members?page=1&per_page=50 GET /api/github/user/repos?page=2&per_page=100
- 將API的版本號放入URL
# 掛起狀態 /api/member/status # 只讀狀態 /api/member/status/v2
- Authentication
- 基本認證機制
- Token認證機制
- OAuth
- 增加頻率限制, 已認證的帳戶已用戶為單位, 未認證的賬戶以ip為單位
X-RateLimit-Limit:60 X-RateLimit-Remaining:56 X-RateLimit-Reset:1372700873
狀態碼
| 狀態碼 | 動詞 | 解釋 |
|---|---|---|
| 200 | * | 服務器成功返回用戶請求的數據 |
| 201 | POST/PUT/PATCH | 用戶新建或修改數據成功 |
| 202 | * | 表示一個請求已經進入后臺排隊（異步任務） |
| 204 | DELETE | 用戶刪除數據成功 |
| 301 | * | 永久重定向 |
| 302 | * | 臨時重定向 |
| 400 | POST/PUT/PATCH | 用戶發出的請求有錯誤，服務器沒有進行新建或修改數據的操作 |
| 401 | * | 表示用戶沒有權限（令牌、用戶名、密碼錯誤） |
| 403 | * | 表示用戶得到授權（與401錯誤相對），但是訪問是被禁止的 |
| 404 | * | 用戶發出的請求針對的是不存在的記錄，服務器沒有進行操作 |
| 406 | GET | 用戶請求的格式不可得（比如用戶請求JSON格式，但是只有XML格式） |
| 410 | GET | 用戶請求的資源被永久刪除，且不會再得到的 |
| 422 | POST/PUT/PATCH | 當創建一個對象時，發生一個驗證錯誤 |
| 500 | * | 服務器發生錯誤，用戶將無法判斷發出的請求是否成功 |
注意事項
- 更新和創建應該返回一個資源描述, 防止API使用者為了獲取更新后的資源而再次調用該API
- 只返回JSON, 而不是XML
- 為了防止API濫用, 給API增加某種類型的速率限制(Github對驗證通過的用戶設置為每小時5000次)
參考鏈接
本文由用戶 jopen 自行上傳分享，僅供網友學習交流。所有權歸原作者，若您的權利被侵害，請聯系管理員。
轉載本站原創文章，請注明出處，并保留原始鏈接、圖片水印。
本站是一個以用戶分享為主的開源技術平臺，歡迎各類分享！