【已轉移】【Java架構：系統架構理論】一篇文章搞掂：RESTful

1、定義

一、起源

• 來源：Roy Fielding的博士論文。
• 目的：理解和評估以網絡爲基礎的應用軟件的架構設計，獲得一個功能強、性能好、適宜通訊的架構。
• 定義：一種實現軟件通訊的架構風格、設計風格，而不是標準；提供了一組設計原則和約束條件。
• 用處：提供一種架構風格，目前也有不少相關實現，咱們能夠理解這種風格，藉助這些實現來實現一個良好通訊軟件架構。

二、定義

REST的名稱解釋：

SOAP：簡單對象訪問協議（英文：Simple Object Access Protocol，簡稱SOAP）。

REST：表述性狀態傳遞（英文：Representational State Transfer，簡稱REST）。

REST是比SOAP更簡單的一個Web應用可選方案。

REST是一種面向資源的架構風格，強調描述應用程序的事物和名詞。

• Representational ：表述性，REST資源可使用各類不一樣的形式進行表述，如XML，JSON，HTML；
• State：狀態，使用REST的時候，咱們關注的是資源的狀態，而不是行爲；
• Transfer：轉移，REST的資源，經過某種形式的表述，在應用之間傳遞轉移。

簡潔地說，REST就是將資源的狀態，以最合適客戶端或服務器的表述方式，在服務器與客戶端之間轉移。

REST與HTTP方法：

URL：REST中，資源經過URL定位和識別。雖然沒有嚴格的URL格式定義，可是一個URL應該能識別資源，而不是簡單的一個命令。由於REST的核心是資源，而不是行爲。

行爲：REST中也有行爲，可是不是在URL中體現，通常經過HTTP行爲來定義，例如CRUD

• Creat:POST
• Read:GET
• Update:PUT/PATCH
• Delete:Delete

最佳實踐

RESTful API的設計實踐

能夠參考這篇文章，翻譯得很好：https://www.cnblogs.com/moonz-wu/p/4211626.html

也能夠參考這個網站的API介紹：https://onlinehelp.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref.htm

個人總結：

一、動詞的使用場景

• GET(選擇)：從服務器上獲取一個具體的資源或者一個資源列表。
• POST(建立)： 在服務器上建立一個新的資源。
• PUT(更新)：以總體的方式更新服務器上的一個資源。
• PATCH(更新)：只更新服務器上一個資源的一個屬性。
• DELETE(刪除)：刪除服務器上的一個資源

二、使用api根和版本管理

• https://example.org/api/v1/*
• https://api.example.com/v1/*

三、使用複數表明集合

• www.xx.com/api/v1/products

四、使用小寫和-分隔符

• www.xx.com/api/v1/product-types

五、使用過濾器傳遞參數

• ?sort-by=name&order=asc

六、同級數據使用...進行分割

• www.xx.com/api/v1/compare/a...b...c

實際應用：

• 增長商品[POST]/api/v1/products/p-id
• 修改商品[PUT]/api/v1/products/p-id
• 刪除商品[DELETE]/api/v1/products/p-id
• 審覈商品[POST]/api/v1/products/p-id/post
• 反審覈商品[DELETE]/api/v1/products/p-id/post
• 失效商品[POST]/api/v1/products/p-id/cancel
• 查詢商品（使用ID）[GET]/api/v1/products/p-id
• 查詢商品（使用編碼）[GET]/api/v1/products/p-id?code=編號
• 商品列表（分頁，參數）[GET]/api/v1/products?page-no=1&page-size=10&sort=code:asc,name:desc,qty:asc&filter=name:eq:名稱條件,code:eq:名稱條件
• 商品列表（分頁，參數，給APP使用）[GET]/api/v1/products?type=app&page-no=1&page-size=10&sort=code:asc,name:desc,qty:asc&search:eq:查找信息