RESTful介紹

REST與技術無關，代表的是一種軟件架構風格，REST是Representational State Transfer的簡稱，中文翻譯為“表征狀態轉移”或“表現層狀態轉化”。阮一峰?理解RESTful架構

RESTful API設計指南

阮一峰 RESTful設計指南

API與用戶的通信協議

使用HTTPS協議。

域名

體現是API

• https://api.example.com
• https://example.org/api/

版本

體現版本

• 將版本信息放在URL中，如：https://api.example.com/v1/
• 將版本信息放在請求頭中。

路徑

網絡上任何東西都是資源，均使用名詞表示（可復數）面向資源編程

• https://api.example.com/v1/zoos
• https://api.example.com/v1/animals
• https://api.example.com/v1/employees

method

根據method不同，進行不同操作

• GET? ? ? ：從服務器取出資源（一項或多項）
• POST? ? ：在服務器新建一個資源
• PUT? ? ? ：在服務器更新資源（客戶端提供改變后的完整資源）
• PATCH? ：在服務器更新資源（客戶端提供改變的屬性）
• DELETE ：從服務器刪除資源

過濾

通過在url上傳參的形式傳遞搜索條件

• https://api.example.com/v1/zoos?limit=10：指定返回記錄的數量
• https://api.example.com/v1/zoos?offset=10：指定返回記錄的開始位置
• https://api.example.com/v1/zoos?page=2&per_page=100：指定第幾頁，以及每頁的記錄數
• https://api.example.com/v1/zoos?sortby=name&order=asc：指定返回結果按照哪個屬性排序，以及排序順序
• https://api.example.com/v1/zoos?animal_type_id=1：指定篩選條件

狀態碼

響應式設置狀態碼

• 200 OK - [GET]：服務器成功返回用戶請求的數據，該操作是冪等的（Idempotent）。
• 201 CREATED - [POST/PUT/PATCH]：用戶新建或修改數據成功。
• 202 Accepted - [*]：表示一個請求已經進入后臺排隊（異步任務）
• 204 NO CONTENT - [DELETE]：用戶刪除數據成功。
• 400 INVALID REQUEST - [POST/PUT/PATCH]：用戶發出的請求有錯誤，服務器沒有進行新建或修改數據的操作，該操作是冪等的。
• 401 Unauthorized - [*]：表示用戶沒有權限（令牌、用戶名、密碼錯誤）。
• 403 Forbidden - [*] 表示用戶得到授權（與401錯誤相對），但是訪問是被禁止的。
• 404 NOT FOUND - [*]：用戶發出的請求針對的是不存在的記錄，服務器沒有進行操作，該操作是冪等的。
• 406 Not Acceptable - [GET]：用戶請求的格式不可得（比如用戶請求JSON格式，但是只有XML格式）。
• 410 Gone -[GET]：用戶請求的資源被永久刪除，且不會再得到的。
• 422 Unprocesable entity - [POST/PUT/PATCH] 當創建一個對象時，發生一個驗證錯誤。
• 500 INTERNAL SERVER ERROR - [*]：服務器發生錯誤，用戶將無法判斷發出的請求是否成功。

錯誤處理

狀態碼是4xx時，應返回錯誤信息，error當做key。

{ error: "Invalid API key" }

返回結果

針對不同操作，服務器向用戶返回的結果應該符合以下規范

• GET /collection：返回資源對象的列表（數組）
• GET /collection/resource：返回單個資源對象；獲取單條數據
• POST /collection：返回新生成的資源對象；返回新增的數據
• PUT /collection/resource：返回完整的資源對象；更新
• PATCH /collection/resource：返回完整的資源對象；局部更新
• DELETE /collection/resource：返回一個空文檔；刪除

Hypermedia API

RESTful API最好做到Hypermedia，即返回結果中提供鏈接，連向其他API方法，使得用戶不查文檔，也知道下一步應該做什么。

{"link": {
? "rel": ? "collection https://www.example.com/zoos",
? "href": ?"https://api.example.com/zoos",
? "title": "List of zoos",
? "type": ?"application/vnd.yourformat+json"
}}