Restful API
文章目錄
簡單記錄 - Restful API實戰
Q：如何做到業務邏輯“一次編寫，隨時接入”？
A：通過遠程調用API ，比較火的方案是“RESTstful API”
RESTful是什麼，簡單來說，RESTful API 是基於HTTP協議產生的一種相對簡單的API設計方案，屬於無狀態傳輸。下面介紹RESTful是什麼-爲什麼-怎麼使用
1、REST是什麼以及它的 6 個限制
要想知道Restful是什麼，先來了解下REST是什麼吧。
REST是什麼？
REST是什麼？
- 萬維網軟件架構風格
- 用來創建網絡服務
起源：REST，是Roy Thomas Fielding在他2000年的博士論文中提出的。
REST，即Representational State Transfer的縮寫, “表現層狀態轉化”。
表現層（Representation）：
我們把"資源"具體呈現出來的形式，叫做它的"表現層"（Representation）。
比如文本可以用txt格式表現，也可以使用JSON格式、二進制格式表現。
狀態轉化（State Transfer）：
數據和狀態的變化
HTTP協議裏面，POST、DELETE、PUT、GET增刪改查，對應四種基本操作：
-
POST用來新建資源
-
DELETE用來刪除資源
-
PUT用來更新資源
-
GET用來獲取資源
數據在互聯網進行傳輸
REST的6個限制
依然不明白REST？
那通過REST的6個限制詳細瞭解它
客戶-服務器（Client-Server）
- 關注點分離
- 服務端專注數據存儲，提升了簡單性
- 前端專注用戶界面，提升了可移植性
數據存儲 用戶交互
無狀態（Stateless）
- 所有用戶會話信息都保存在客戶端
- 每次請求必須包括所有信息，不能依賴上下文信息
- 服務端不用保存會話信息，提升了簡單性、可靠性、可見性
緩存的作用
緩存（Cache）
- 所有服務端響應都要被標爲可緩存或不可緩存
- 減少前後端交互，提升了性能
統一接口（Uniform Interface）
- 接口設計儘可能統一通用，提升了簡單性、可見性
- 接口與實現解耦，使前後端可以獨立開發迭代
分層系統（Layered System）
- 每層只知道相鄰的一層，後面隱藏的就不知道了
- 客戶端不知道是和代理還是真實服務器通信
- 其他層：安全性、負載均衡、緩存層等
按需代碼（Code - On - Demand 可選）
- 客戶端可以下載運行服務器傳來的代碼（比如 JS）
- 通過減少一些功能，簡化了客戶端
統一接口的限制
資源的標識
- 資源是如何可以命名的事物，比如用戶、評論等
- 每個資源可以通過URI被唯一地標識
- https://api.github.com/users
- https://api.github.com/users/liuawen
URI 統一資源標識符（Uniform Resource Identifier）
URL 統一資源定位器 （Uniform Resource Locator）
URI 唯一標識
網上的資源唯一地標識
提供表述來操作資源
- 表述就是Representation ，比如JSON、XML等
- 客戶端不能直接操作（比如SQL）服務端資源
- 客戶端應該通過表述（比如JSON）來操作資源
https://developer.github.com/v3/repos/
自描述信息
-
每個消息（請求或響應）必須提供足夠的信息讓接受者理解
-
媒體類型（application/json、application/xml）
-
HTTP方法：GET（查）、POST（增）、DELECT（刪）
-
是否緩存：Cache-Control
HTTP verbs
HTTP協議 標準
超媒體作爲應用狀態引擎
-
超媒體：帶文字的鏈接
-
應用狀態：一個網頁
-
引擎：驅動、跳轉
-
合起來：點擊鏈接跳轉到另一個網頁
2、 Restful是什麼
Restful定義以及Restful對於資源的定義
Restful是什麼
RESTful架構，就是目前流行的一種互聯網軟件架構
Restful
如果一個架構符合REST原則，就稱它爲RESTful架構。
符合REST架構風格的API
本質：一種軟件架構風格
核心：面向資源
解決的問題：
- 降低開發的複雜性
- 提高系統的可伸縮性
RESTful API具體什麼樣子？
基本的URI，如 https://api.github.com/users
標準HTTP方法，如GET,POST,PUT,PATCH,DELETE
傳輸的數據媒體類型，如JSON，XML
現實舉例
-
GET / users # 獲取users列表
-
GET /users/12# 查看某個具體的user
-
POST/users# 新建一個user
-
PUT /users/12# 更新user12
-
DELETE/users/12# 刪除user12
從資源出發
從資源出發
設計概念和準則
- 網絡上的所有事物都可以被抽象爲資源。
- 每一個資源都有唯一的資源標識，對資源的操作不會改變這些標識。
- 所有的操作都是無狀態的。
資源
Q：那什麼是資源呢？
A：所謂“資源”，就是網絡上的一個實體，或者說是網絡上的一個具體信息,可以是文本、圖片、視頻等
每種資源對應一個特定的URI（統一資源標識符（Uniform Resource Identifier））。要獲取這個資源，訪問它的URI就可以，因此URI就成了每一個資源的地址或獨一無二的識別符。
3、爲什麼要使用Restful
HTTP協議-URL
HTTP是一個屬於應用層的協議，特點是簡捷、快速。
schema：//host[:port]/path[?quert-string] [#anchor]
-
schema 指定底層使用的協議（例如：http，https,ftp）
-
host 服務器的IP地址或者域名
-
port 服務器端口，默認爲80
-
path 訪問資源的路徑
-
query0string 發送給http服務器的數據
-
anchor 錨
HTTP協議-請求
HTTP協議-請求
組成格式：請求行、消息報頭、請求正文
請求行
格式如下：Method Request-URI HTTP-Version CRLF
舉例
GET / HTTP / 1.1 CRLF
請求方法
- GET 請求獲取Request-URI所標識的資源
- POST 在Request-URI所標識的資源後附加新的數據
- HEAD 請求獲取由Request-URI所標識的資源的響應消息
獲取
發送數據
- PUT 請求服務器存儲一個資源 ，並用Request-URI作爲其標識
- DELETE 請求服務器刪除Request-URI所標識的資源
- OPTIONS 請求查詢服務器的性能，或者查詢與資源相關的選項和需求
HTTP協議-響應
HTTP協議-響應
組成格式：狀態行、消息報頭、響應正文
狀態行
HTTP-Version Status-Code Reason-Phrase CRLF
HTTP/1.1 200 OK
常用狀態碼
-
200 OK //客戶端請求成功
-
400 Bad Request //客戶端請求有語法錯誤，不能被服務器所理解
-
401 Unauthorized //服務器收到請求，但是拒絕提供服務
-
404 Not Found //請求資源不存在
5xx服務器錯誤
- 500 Internal Server Error //服務器發生不可預期的錯誤
- 503 Server Unavailable //服務器當前不能處理客戶端的請求
404 Not Found
RESTful架構與其他架構的區別
SOAP WebService
WebService是一種跨編程語言和跨操作系統平臺的遠程調用技術
WebService通過HTTP協議發送請求和接受結果時採用XML格式封裝，並增加了一些特定的HTTP消息頭，這些特定的HTTP消息頭和XML內容格式就是SOAP協議。
WebService 、SOAP協議、RESTful架構與WebService
RESTful架構與其他架構的區別
效率和易用性
SOAP由於各種需求不斷擴充本身協議的內容，導致在SOAP處理方面的性能有所下降。同時在易用性方面以及學習成本上也有所增加。
RESTful由於其面向資源接口設計以及操作抽象簡化了開發者的不良設計,同時也最大限度的利用了Http最初的應用協議設計理念。
安全性
RESTful對於資源型服務接口來說很合適,同時特別適合對於效
率要求很高,但是對於安全要求不高的場景。
SOAP的成熟性可以給需要提供給多開發語言的, 對於安全性
要求較高的接口設計帶來便利。所以覺得純粹說什麼設計模
式將會佔據主導地位沒有什麼意義,關鍵還是看應用場景。
restful適合做什麼開發
接口或者應用
4、 如何使用Restful
如何設計RESTful API
-
資源路徑（URI）
-
HTTP動詞
-
過濾信息
-
狀態碼
-
錯誤處理
-
返回結果
請求設計規範
- URI使用名詞，儘量用複數，如/users
- URI使用嵌套表示關聯關係，如 /users/12/repos/5
- 使用正確的HTTP方法，如GET/POST/PUT/DELETE
- 不符合CRUD的情況：POST/action/子資源
資源路徑
在RESTful架構中，每個網址代表一種資源，所以網址中不能有動詞，只能有名詞，一般來說API中的名詞應該使用複數。goods、users等。
舉例
舉例來說,有一個API提供動物園( zoo )的信息,還包括各種動物和僱員的信息。則它的路徑應該設計成下面這樣。
https://api.example.com/v1/zoos //動物園資源
https://api.example.com/v1/animals //動物園資源
https://api.example.com/v1/employees //動物園資源
v1版本、http請求頭中 或者 名詞複數
獲取一個動物 animals/id=1
資源的設計
http 動詞 四種操作 創建 更新 讀取 刪除
HTTP動詞
對於資源的操作（CURD），由HTTP動詞（謂詞）表示
-
GET：從服務器取出資源（一項或多項）。
-
POST：在服務器新建一個資源。
-
PUT：在服務器更新資源（客戶端提供改變後的完整資源）
-
PATCH：在服務器更新資源（客戶端提供改變的屬性）。
-
DELETE：從服務器刪除資源。
put更新資源 patch只會返回更新的數據 比如改密碼 密碼變了就返回密碼。
舉例
-
POST /zoos:新建一個動物園
-
GET /zoos/ID:獲取某個指定動物園的信息
-
PUT /zoos/ID: 更新某個指定動物園的信息
-
DELETE /zoos/ID:刪除某個動物園
刪除動物園，動物園裏的動物都刪除
POST新建 GET 獲取 PUT 更新 DELETE 刪除
過濾信息
如果記錄數量很多，服務器不可能都將它們返回給用戶。
API應該提供參數，過濾返回結果。
過濾信息，某個常數。
舉例
- ?offset=10:指定返回記錄的開始位置。
- ?page=2&per_page=100:指定第幾頁，以及每頁的記錄數。
- ?sortby=name&order=asc:指定返回結果排序，以及排序順序。
- ?animal_type_id=1:指定篩選條件。
過濾信息
用戶自己設計的
offset開始位置
狀態碼
標準的
服務器向用戶返回的狀態碼和提示信息，使用標準HTTP狀態碼。
- 200 OK 服務器成功返回用戶請求的數據，該操作是冪等的。
- 201 CREATED created 新建或修改數據成功
- 204 NO CONTENT 刪除數據成功
200 OK
201新建修改204刪除，用得比較少的。
- 400 BAD REQUEST request 用戶發出的請求有錯誤，該操作是冪等的。
- 401 Unauthorized 表示用戶沒有認證，無法進行當前操作。
- 403 Forbidden 表示用戶訪問是被禁止的。
客戶端的請求有問題
401 沒有認證
403 提供了 但參數不足 或者權限不夠
- 422 Unprocesable Entity 當創建一個對象時，發生一個驗證錯誤。
- 500 INTERNAL SERVER ERROR internal server error 服務器發生錯誤，用戶將無法判斷髮出的請求是否成功。
422
驗證錯誤 後端需要用戶名 密碼 前端只提供了一個用戶名 錯誤了 密碼不能爲空
500
服務器錯誤
錯誤處理
422 參數錯誤 500
錯誤處理
輸出JSON格式錯誤信息
如果狀態碼是4xx或者5xx，就應該向用戶返回出錯信息。一般來說，返回的信息中將error作爲鍵名，出錯信息作爲鍵值即可
{
"error":"參數錯誤"
}
返回結果
輸出JSON數組或JSON對象
返回結果
針對不同操作，服務器向用戶返回的結果應該符合以下規範：
-
GET/collections:返回資源對象的列表（數組）
-
GET/collections/identity:返回單個資源對象
-
POST/collections:返回新生成的資源對象。
-
PUT/collections/identity：返回完整的資源對象
-
PATCH/collections/identity：返回被修改的屬性
-
DELECT/collections/identity：返回一個空文檔
不存在返回404
參數
PUT 完整的 PATCH更新的
DELETE 空的
設計RESTful API
表單不是隻支持GET和POST提交麼。那怎麼支持put、delete請求方式呢不懂？
HTTP/1.1協議中共定義了八種方法（有時也叫“動作”）來表明Request-URI指定的資源的不同操作方式：具體方法可以上網查詢
你說的表單指的是form表單吧，method 屬性規定如何發送表單數據（表單數據發送到 action 屬性所規定的頁面）。表單數據可以作爲 URL 變量（method=“get”）或者 HTTP post （method=“post”）的方式來發送。
5、 小結
RESTful設計要素
RESTful應用場景
基於HTTP請求頭的身份認證
REST，即Representational State Transfer的縮寫, “表現層狀態轉化”。
如果一個架構符合REST原則，就稱它爲RESTful架構。
解決的問題：
- 降低開發的複雜性
- 提高系統的可伸縮性
基本的URI，如 https://api.github.com/users
標準HTTP方法，如GET,POST,PUT,PATCH,DELETE
傳輸的數據媒體類型，如JSON，XML
去選擇 不能因爲restful而restful 嗯嗯
6、參考資料
1、 理解RESTful架構