【RESTful】RESTful API 設計規範
概念
本質:一種軟體架構風格 核心:面向資源設計的API
解決問題:
- 降低開發的複雜性
- 提高系統的可伸縮性
例如:設計一套API,為多個終端服務。
設計概念和準則
- 網路上的所有事物都可以被抽象為資源
- 每一個資源都有唯一的資源標識,對資源的操作不會改變這些標識
- 所有的操作都是無狀態的(本次操作、下次操作、上次操作之間無關係)
資源:網路上的一個實體、具體資訊。
HTTP
RESTful 與HTTP協議操作無關,但是它是按照HTTP的思想進行設計的,所以有必要知道HTTP
schema://host[:port]/path[?query-string][#author]
- shceme 指定低層使用的協議(如http,https,ftp)
- host 伺服器的IP地址或域名
- port 伺服器埠,預設為80
- path 訪問資源的路徑
- query-string 傳送給http伺服器的資料,常用於對資源進行篩選操作
- anchor 錨,連結
請求
- 格式:請求行、訊息報頭、請求正文
請求行格式: 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-Version Status-Code Reason-Phrase CRLF
如: HTTP/1.1 200 OK
- 常用響應狀態碼(在RESTful 中有重要應用)
200 OK //客戶端請求成功
400 Bad Request //客戶端請求有語法錯誤,不能被伺服器所理解
401 Unanthorized //伺服器收到請求,但是伺服器拒絕提供服務
404 Not Found //請求資源不存在
500 Internal Serval Error //伺服器發生不可預期的錯誤
503 Server Unavailable // 伺服器當前不能處理客戶端的請求
RESTful 架構與其他架構的區別
API 的開發方式不止一種,另一種比較流行的開發方式是SOAP WebService。
SOAP WebService
WebService 是一種跨程式語言和跨作業系統平臺的遠端呼叫技術。其通過HTTP協議傳送請求和接收結果時採用XML格式封裝,並增加了一些特定的HTTP訊息頭,這些特定的HTTP訊息頭和XML內容格式就是SOAP協議。
對比
- 效率與易用性:SOAP由於各種需求不斷擴充其本身協議的內容,導致在SOAP處理方面的效能有所下降。同時在易用性方面以及學習成本上也有所增加。而RESTful API 在請求方法、資源、地址都進行了規範,其最大限度的利用了HTTP最初的應用協議的設計理念。
- 安全性:RESTful 對於資源型伺服器介面比較適合,適合對於效率要求很高,但是對於安全要求不高的場景。SOAP 的成熟性可以給需要提供給多開發語言的,對於安全性的要求較高的介面設計帶來便利,你可以在客戶端和服務端應用證書進行安全措施。所以關鍵看應用場景。
使用RESTful
設計RESTful API
-
資源路徑(URI):RESTful的核心是面向資源,如何規劃資源路徑很重要
-
HTTP動詞(請求方式):如get,post,delete,put
-
過濾資訊:例如獲取資源列表時有分頁操作/查詢操作,這時要合理分配過濾資訊,過濾資訊設定太多,有可能會違反RESTful API 關於URI方面的限定。
-
狀態碼:當客戶端傳送一個請求時,服務端應當響應什麼狀態碼
-
錯誤處理:如當發現客戶端傳入的引數有問題時,該返回什麼樣的狀態資訊。
-
返回結果:如POST資源的時候,需要返回一個資源例項;GET資源列表時,需要返回一個資源陣列;
資源路徑
在RESTful架構中,每個網址代表一個資源,所以網址中不能有動詞,只能有名詞。一般而言,API中的名詞應該使用複數。例如,使用users反映使用者資源的URI,而不是使用user。
例如:有一個API提供動物園(zoo)的資訊,還包括各種動物和僱員的資訊,那麼它的資源路徑應設計成如下樣子。
https://api.example.com/v1/zoos //動物園資源。使用https協議頭;加入v1版本號,因為以後可能會更改api。版本號的加入有兩種做法,一種是加入到地址中,另一種是加入到HTTP請求頭中;zoos複數
https://api.example.com/v1/animals //動物資源
https://api.example.com/v1/employees //僱員資源
HTTP動詞
對資源的操作有建立、讀取、更新、刪除(CURD),由HTTP動詞表示。
- GET : 從伺服器去除資源
- POST :在伺服器新建一個資源
- PUT:在伺服器更新資源(客戶端提供改變後的完整資源,服務端返回完整的更新欄位)
- PATCH:在伺服器更新資源(客戶端提供改變的屬性,服務端返回只發生了更新的欄位)
- DELETE:從伺服器刪除資源
例如:
POST/zoos : 新建一個動物園
GET/zoos/ID : 獲取某個指定動物園的資訊
PUT/zoos/ID : 更新某個指定動物園的資訊
DELETE/zoos/ID : 刪除某個動物園
過濾資訊
如果記錄數量過多,伺服器不可能都將它們返回給使用者。這時就需要進行篩選。篩選時,API應該提供一個引數,過濾一下返回的結果。
例如:
?offset = 10 :指定返回記錄的開始位置
?page = 2&per_page = 100 :指定第幾頁,以及每頁的記錄數
?sortby = name&order = asc :指定返回結果排序,以及排序順序
?animal_type_id = 1 :指定篩選條件
狀態碼
伺服器向用戶返回的狀態碼和提示資訊,使用標準的HTTP狀態碼
- 200 OK 伺服器成功返回使用者請求的資料
- 201 CREATED 新建或修改資料成功
- 204 NO CONTENT 刪除資料成功
- 400 BAD REQUEST 使用者發出的請求有錯誤
- 401 Unauthorized 表示使用者沒有認證,無法進行當前操作
- 403 Forbidden 表示使用者的訪問是被禁止的
- 422 Unprocesable Entity 當建立一個物件時,發生一個驗證錯誤。例如建立使用者資源時需要使用者名稱、密碼,而前端只提供使用者名稱欄位,那麼就要返回一個422 狀態碼,並返回錯誤資訊:”密碼不能為空“
- 500 INTERNAL SERVER ERROR 伺服器內部錯誤,此時服務端無法處理任何請求。
錯誤處理
如果狀態碼是4xx或5xx,就應該向使用者返回出錯資訊。一般而言,返回的資訊中將error作為鍵名,出錯資訊作為鍵值即可,例如:
{
"error":"引數錯誤"
}
返回結果
針對不同操作(如GET,POST),伺服器向用戶返回的結果應該符合以下規範:
- GET/collections: 返回資源物件的列表(陣列)
- GET/collections/identity : 讀取資源時,傳入識別符號(identity),服務端返回識別符號指定的單個資源物件
- POST/collections : 返回新生成的資源物件
- PUT/collections/identity : 返回完整的資源物件
- PATCH/collections/identity : 返回被修改的屬性
- DELETE/collections/identity : 返回一個204狀態碼和空響應體
DHC Client 用於測試API
- 安裝DHC 谷歌瀏覽器外掛:
名為: 基於REST的Web服務客戶端
先下載: http://chromecj.com/web-development/2015-03/401.html
或在谷歌商店 :https://chrome.google.com/webstore/detail/rest-web-service-client/ecjfcmddigpdlehfhdnnnhfgihkmejin?hl=zh-CN
然後安裝。
本地開發環境搭建
-
安裝PHP環境整合包 XAMPP 或 upupw
-
新增虛擬主機,以及取消跨站目錄限制
httpd-vhosts.conf
檔案中 找到新增的域名,將php_admin_value xxx
這句開頭加入井號進行註釋 -
新增虛擬主機的本地hosts解析 : 更改本地hosts檔案,新增
127.0.0.1 api.com
本地域名解析
確認設計要素
專案需求
- 使用者登入、註冊
- 文章發表、編輯、管理、列表
確認設計要素
- 資源路徑: /users , /articles
- HTTP動詞: GET,POST,DELETE,PUT
- 過濾資訊: 文章分頁篩選
- 狀態碼: 200,404,422,403…
- 錯誤處理:輸出JSON格式錯誤資訊
- 返回結果:輸出JSON陣列或JSON物件
資料庫設計
在資料庫中新建2張表:
- 使用者表: ID、使用者名稱、密碼、註冊時間
- 文章表: 文章ID、標題、內容、發表時間、使用者ID
新增.htaccess Apache重寫檔案
之後就可以在IDE中進行相應的開發編碼工作。