RESTful雜記

前言

在網上找了許久的關於REST的資料，發現網上大部分都是說的比較片面，雖然有部分說出了本質，但也沒有詳細提出，因此在這裏記錄一下。

RESTful是什麼

首先，維基百科是這樣說的：

表現層狀態轉換（REST，英文：Representational State Transfer）是Roy Thomas Fielding博士於2000年在他的博士論文中提出來的一種萬維網軟件架構風格，目的是便於不一樣軟件/程序在網絡（例如互聯網）中互相傳遞信息

這樣的概念有點難以理解，瞭解一個東西，一般能夠先了解他的背景，他是爲了解決什麼問題而出現的？

Fielding是一個很是重要的人，他是HTTP協議（1.0版和1.1版）的主要設計者、Apache服務器軟件的做者之1、Apache基金會的第一任主席。

而下面則是他在論文中提出REST的目的。

"本文研究計算機科學兩大前沿----軟件和網絡----的交叉點。
長期以來，軟件研究主要關注軟件設計的分類、設計方法的演化，不多客觀地評估不一樣的設計選擇對系統行爲的影響。
而相反地，網絡研究主要關注系統之間通訊行爲的細節、如何改進特定通訊機制的表現，經常忽視了一個事實，那就是改變應用程序的互動風格比改變互動協議，對總體表現有更大的影響。
我這篇文章的寫做目的，就是想在符合架構原理的前提下，理解和評估以網絡爲基礎的應用軟件的架構設計，獲得一個功能強、性能好、適宜通訊的架構。"

這段話比較繞口，總結一下，就是REST是一個爲了進一步解耦client和server的架構風格。

REST風格

首先，根據論文能夠得知，REST風格是由約束來定義的

Web 架構背後的設計基本原理，可以被描述爲由一組應用於架構中元素之上的約束組成
的架構風格。當將每一個約束添加到進化中的風格時，會產生一些影響。經過檢查這些影響，
咱們就可以識別出 Web 的約束所致使的屬性。而後就可以應用額外的約束來造成一種新的
架構風格，這種風格可以更好地反映出現代 Web 架構所期待的屬性。

client-servet

client-server之間的解耦，服務提供者和服務消費者互不影響，也是咱們常說的先後端分離。先後端分離的優點是比較顯著的，改善了用戶接口跨多個平臺的可移植性；同時經過簡化服務器組件，改善了系統的可伸縮性。

無狀態

這個約束使架構擁有了可見性、可靠性和可伸縮性等三個架構屬性。
可見性是指能單獨的理解一個請求，可靠性是減輕了從局部故障中恢復的任務量， 可伸縮性是指爲沒必要在多個請求之間保 存狀態，從而容許服務器組件迅速釋放資源。

可緩存

優點明顯，不贅述。

統一接口

它強調組件之間要有 一個統一的接口。經過在組件接口上應用通用性的軟件工程原則，總體的系統架 構獲得了簡化，交互的可見性（經過方法名即知道動做）也獲得了改善。實現與它們所提供的服務是解耦的，這促進了獨立的可進化性。
然而，付出的代價是，統一接口下降了效率，由於信息都使用標準化的形 式來轉移，而不能使用特定於應用的需求的形式。（只能使用put post delete get patch等）
解決方法：爲須要的動做增長一個 endpoint，使用 POST 來執行動做，好比 POST /resend 從新發送郵件。

分層系統

分層系統風格經過限制組件的行爲（即，每一個組件只 能「看到」與其交互的緊鄰層），將架構分解爲若干等級的層。經過將組件對系統的知識限 制在單一層內，爲整個系統的複雜性設置了邊界，而且提升了底層獨立性。
咱們可以使用層來封裝遺留的服務，使新的服務免受遺留客戶端的影響，經過將不經常使用的功能轉移到一個共享的中間組件中，從而簡化組件的實現。中間組件還可以經過支持跨多個網絡和處理器的負 載均衡，來改善系統的可伸縮性。
也就是說服務器和客戶端之間的中間層（代理，網關等）代替服務器對客戶端的請求進行迴應，而客戶端不須要關心與它交互的組件以外的事情。

按需加載代碼

經過下載並執行 applet 形式或腳本形式的代碼，REST容許對客戶端的功能進行擴展。經過減小必須被預先實現的功能的數目，簡化了客戶端的開發。容許在部署以後下載功能代 碼也改善了系統的可擴展性。然而，這也下降了可見性，所以它只是REST的一個可選的約束。

設計原則（GITHUB API）

瞭解了REST是什麼東西后，咱們才能設計出合適的API，如下是根據GITHUB API來總結的（基本參考自：https://cizixs.com/2016/12/12...）

使用https

這個和 Restful API 自己沒有很大的關係，可是對於增長網站的安全是很是重要的。

API地址和版本

若是 API 變化比較大，能夠把 API 設計爲子域名，好比 https://api.github.com/v3

響應內容

儘可能使用JSON，JSON在多種語言中支持，若是須要使用其餘的如XML， 應該在請求頭部 Accept 中指定

以資源爲中心

資源分爲單個文檔和集合，儘可能使用複數來表示資源，單個資源經過添加id或者name等來表示。一個資源能夠有多個不一樣的 URL。資源能夠嵌套，經過相似目錄路徑的方式來表示，以體現它們之間的關係。

/users/:username/repos
/users/:org/repos
/repos/:owner/:repo
/repos/:owner/:repo/tags
/repos/:owner/:repo/branches/:branch

使用正確的METHOD

這個比較容易理解，即get（獲取），post（建立），put（替換），patch（局部更新），delete（刪除），head（獲取某個資源的頭部信息。好比只想瞭解某個文件的大小，某個資源的修改日期等）

對於不符合CURD的狀況，能夠採用參數協助

如分頁page=2&per_page=100：指定第幾頁，以及每頁的記錄數，或者增長一個endpoint，如上面說的重發郵件，或者將動做轉換爲資源（Github:好比「喜歡」一個 gist，就增長一個 /gists/:id/star 子資源，而後對其進行操做：「喜歡」使用 PUT /gists/:id/star，「取消喜歡」使用 DELETE /gists/:id/star）

狀態碼

https://developer.mozilla.org...

• 2XX：請求正常處理並返回
• 3XX：重定向，請求的資源位置發生變化
• 4XX：客戶端發送的請求有錯誤
• 5XX：服務器端錯誤

錯誤處理

返回錯誤時，在響應內容里加上具體的錯誤信息。

Hypermedia API

當服務端修改API時，客戶端不須要知道和修改。

驗證和受權， OAUTH2等

限流， 參考github

https://developer.github.com/...
對用戶的請求限流以後，要有方法告訴用戶它的請求使用狀況，Github API 使用的三個相關的頭部：

X-RateLimit-Limit: 用戶每一個小時容許發送請求的最大值
X-RateLimit-Remaining：當前時間窗口剩下的可用請求數目
X-RateLimit-Rest: 時間窗口重置的時候，到這個時間點可用的請求數量就會變成 X-RateLimit-Limit 的值

編寫清晰的文檔

REST與http的關係？

我的理解是REST是一種架構風格，而http則是這種架構實現下的一種協議。

比較（以操做爲中心）

• 以操做爲中心可見性低，即不夠清晰。
• 在除了CURD的接口外，以操做爲中心調用效率高，不須要hack。
• 以操做爲中心沒有HyperMidea Api，修改api效率低，須要客戶端服務端同時修改。
• 以操做爲中心上手難度係數大。
• 以資源爲中心，簡單數據操做，無事務處理，開發和調用簡單， 以操做爲中心，清晰的規範標準定義，可以處理較爲複雜的面向活動的服務

在一般的軟件開發過程當中，咱們經常須要分析達成某個目標所須要使用的業務邏輯，併爲業務邏輯的執行提供一系列運行接口。在一些Web服務中，這些接口經常表達了某個動做，如將商品放入購物車，提交訂單等。這一系列動做組合在一塊兒就能夠組成完成目標所須要執行的業務邏輯。在須要調用這些接口的時候，軟件開發人員須要向這些接口所在的URL發送一個請求，從而驅使服務執行該動做