【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中進行相應的開發編碼工作。