避免本身寫的 url 被diss！建議看看這篇RestFul API簡明教程！

你們好我是 Guide 哥！這是個人第 210 篇優質原創！這篇文章主要分享了後端程序員必備的 RestFul API 相關的知識。

RestFul API 是每一個程序員都應該瞭解並掌握的基本知識，咱們在開發過程當中設計 API 的時候也應該至少要知足 RestFul API 的最基本的要求（好比接口中儘可能使用名詞，使用 POST 請求建立資源，DELETE 請求刪除資源等等，示例：GET /notes/id：獲取某個指定 id 的筆記的信息）。

若是你看 RestFul API 相關的文章的話通常都比較晦澀難懂，包括我下面的文章也會提到一些概念性的東西。可是，實際上咱們平時開發用到的 RestFul API 的知識很是簡單也很容易歸納！舉個例子,若是我給你下面兩個 url 你是否是立馬能知道它們是幹什麼的！這就是 RestFul API 的強大之處！

RestFul API 能夠你看到 url + http method 就知道這個 url 是幹什麼的，讓你看到了 http 狀態碼（status code）就知道請求結果如何。

GET    /classs：列出全部班級
POST   /classs：新建一個班級
複製代碼

下面的內容只是介紹了我以爲關於 RestFul API 比較重要的一些東西，歡迎補充。

1、重要概念

REST,即 REpresentational State Transfer 的縮寫。這個詞組的翻譯過來就是"表現層狀態轉化"。這樣理解起來甚是晦澀，實際上 REST 的全稱是 Resource Representational State Transfe ，直白地翻譯過來就是 「資源」在網絡傳輸中以某種「表現形式」進行「狀態轉移」 。若是仍是不能繼續理解，請繼續往下看，相信下面的講解必定能讓你理解到底啥是 REST 。

咱們分別對上面涉及到的概念進行解讀，以便加深理解，不過實際上你不須要搞懂下面這些概念，也能看懂我下一部分要介紹到的內容。不過，爲了更好地能跟別人扯扯 「RestFul API」我建議你仍是要好好理解一下！

• 資源（Resource） ：咱們能夠把真實的對象數據稱爲資源。一個資源既能夠是一個集合，也能夠是單個個體。好比咱們的班級 classs 是表明一個集合形式的資源，而特定的 class 表明單個個體資源。每一種資源都有特定的 URI（統一資源定位符）與之對應，若是咱們須要獲取這個資源，訪問這個 URI 就能夠了，好比獲取特定的班級：/class/12。另外，資源也能夠包含子資源，好比 /classs/classId/teachers：列出某個指定班級的全部老師的信息
• 表現形式（Representational）："資源"是一種信息實體，它能夠有多種外在表現形式。咱們把"資源"具體呈現出來的形式好比 json，xml，image,txt 等等叫作它的"表現層/表現形式"。
• 狀態轉移（State Transfer） ：你們第一眼看到這個詞語必定會很懵逼？心裏 BB：這尼瑪是啥啊？ 大白話來講 REST 中的狀態轉移更多地描述的服務器端資源的狀態，好比你經過增刪改查（經過 HTTP 動詞實現）引發資源狀態的改變。ps:互聯網通訊協議 HTTP 協議，是一個無狀態協議，全部的資源狀態都保存在服務器端。

綜合上面的解釋，咱們總結一下什麼是 RESTful 架構：

1. 每個 URI 表明一種資源；
2. 客戶端和服務器之間，傳遞這種資源的某種表現形式好比 json，xml，image,txt 等等；
3. 客戶端經過特定的 HTTP 動詞，對服務器端資源進行操做，實現"表現層狀態轉化"。

2、REST 接口規範

一、動做

• GET ：請求從服務器獲取特定資源。舉個例子：GET /classs（獲取全部班級）
• POST ：在服務器上建立一個新的資源。舉個例子：POST /classs（建立班級）
• PUT ：更新服務器上的資源（客戶端提供更新後的整個資源）。舉個例子：PUT /classs/12（更新編號爲 12 的班級）
• DELETE ：從服務器刪除特定的資源。舉個例子：DELETE /classs/12（刪除編號爲 12 的班級）
• PATCH ：更新服務器上的資源（客戶端提供更改的屬性，能夠看作做是部分更新），使用的比較少，這裏就不舉例子了。

二、路徑（接口命名）

路徑又稱"終點"（endpoint），表示 API 的具體網址。實際開發中常見的規範以下：

1. 網址中不能有動詞，只能有名詞，API 中的名詞也應該使用複數。 由於 REST 中的資源每每和數據庫中的表對應，而數據庫中的表都是同種記錄的"集合"（collection）。若是 API 調用並不涉及資源（如計算，翻譯等操做）的話，能夠用動詞。 好比：GET /calculate?param1=11&param2=33
2. 不用大寫字母，建議不用中槓 - 不用下槓 _ 好比邀請碼寫成 invitation-code而不是 invitation_code

Talk is cheap！來舉個實際的例子來講明一下吧！如今有這樣一個 API 提供班級（class）的信息，還包括班級中的學生和教師的信息，則它的路徑應該設計成下面這樣。

接口儘可能使用名詞，禁止使用動詞。 下面是一些例子：

GET    /classs：列出全部班級
POST   /classs：新建一個班級
GET    /classs/classId：獲取某個指定班級的信息
PUT    /classs/classId：更新某個指定班級的信息（通常傾向總體更新）
PATCH  /classs/classId：更新某個指定班級的信息（通常傾向部分更新）
DELETE /classs/classId：刪除某個班級
GET    /classs/classId/teachers：列出某個指定班級的全部老師的信息
GET    /classs/classId/students：列出某個指定班級的全部學生的信息
DELETE classs/classId/teachers/ID：刪除某個指定班級下的指定的老師的信息
複製代碼

反例：

/getAllclasss
/createNewclass
/deleteAllActiveclasss
複製代碼

理清資源的層次結構，好比業務針對的範圍是學校，那麼學校會是一級資源:/schools，老師: /schools/teachers，學生: /schools/students 就是二級資源。

三、過濾信息（Filtering）

若是咱們在查詢的時候須要添加特定條件的話，建議使用 url 參數的形式。好比咱們要查詢 state 狀態爲 active 而且 name 爲 guidegege 的班級：

GET    /classs?state=active&name=guidegege
複製代碼

好比咱們要實現分頁查詢：

GET    /classs?page=1&size=10 //指定第1頁，每頁10個數據
複製代碼

四、狀態碼（Status Codes）

狀態碼範圍：

2xx：成功	3xx：重定向	4xx：客戶端錯誤	5xx：服務器錯誤
200 成功	301 永久重定向	400 錯誤請求	500 服務器錯誤
201 建立	304 資源未修改	401 未受權	502 網關錯誤
		403 禁止訪問	504 網關超時
		404 未找到
		405 請求方法不對

三 HATEOAS

RestFul 的極致是 hateoas ，可是這個基本不會在實際項目中用到。

上面是 RESTful API 最基本的東西，也是咱們平時開發過程當中最容易實踐到的。實際上，RESTful API 最好作到 Hypermedia，即返回結果中提供連接，連向其餘 API 方法，使得用戶不查文檔，也知道下一步應該作什麼。

好比，當用戶向 api.example.com 的根目錄發出請求，會獲得這樣一個文檔。

{"link": {
  "rel":   "collection https://www.example.com/classs",
  "href":  "https://api.example.com/classs",
  "title": "List of classs",
  "type":  "application/vnd.yourformat+json"
}}
複製代碼

上面代碼表示，文檔中有一個 link 屬性，用戶讀取這個屬性就知道下一步該調用什麼 API 了。rel 表示這個 API 與當前網址的關係（collection 關係，並給出該 collection 的網址），href 表示 API 的路徑，title 表示 API 的標題，type 表示返回類型 Hypermedia API 的設計被稱爲HATEOAS。

在 Spring 中有一個叫作 HATEOAS 的 API 庫，經過它咱們能夠更輕鬆的建立除符合 HATEOAS 設計的 API。