restful
什麼是API
API全稱Aplication Programming Itererface即應用程序編程接口， 我們在開發應用程序時經常用到。API作爲接口，用來“連接”兩個不同的系統，並使其中一方爲另一 方提供服務，比如在操作系統上運行的應用程序能夠訪問操作系統所提供的API,並通過這些API來調用操,作系統的各種功能。因此，API 是一個系統向外暴露或公開的一套接口， 通過這些接口，外部應用程序能夠訪問該系統。在Web應用程序中，Web API具有同樣的特性，它作爲一個Web應用程序，向外提供了,在Web應用程序中，Web API具有同樣的特性，它作爲一個Web應用程序，向外提供了一些接口， 這些接口的功能通常是對數據進行操作,一些接口， 這些接口的功能通常是對數據進行操作(如獲取或修改數據等)，它們能夠被外部應用程序，比如桌面應用程序、手機應用甚至其他Web應用程序(如ASP.NET Core MVC視圖應用、單頁Web應用)等訪問並調用。WebAPI能夠實現不同應用程序之間的訪問，它與平臺或編程語言無關，可以使用不同的技術來構建Web API,如Java、.NET等;
什麼是REST
REST(Representational State Transfer) 表述性傳遞狀態，Roy Fielding博士在2000年他的博士論文中提出來的一種軟件架構風格，作爲一種web服務的設計與開發方式，Rest可以降低開發的複雜性，提高系統的可伸縮性。
REST是一種基於資源的架構風格，在REST中，資源(Resource)是最基本的概念任何能夠命名的對象都是資源，如：user,team,order,docment。他表示web服務要操作的一個實體，一個資源具有一個統一資源標識符。(Uniform Resource Identifier URI),如 users/123。通過資源能夠標識並訪問資源。
資源標識
主鍵編號進行標識
資源集合
除了單個資源外，資源集合表示多個相同類型的資源，如users。在系統設計時，不同的實體之間往往存在着某種關聯關係。如一個用戶有多個訂單。同樣，在REST中，這種關聯關係也能夠有資源之間的層次關係體現出來。如users/123/orders/1
由於REST資源爲中心，因此REST接口的端點(Endpoint)均以資源或資源集合結尾，它不像其他形式的WEB服務一樣以動詞結尾，如api/GetUserInfo或者api/UpdateUserInfo。在REST中，對資源的動作或操作是通過HTTP方法來完成的。如下
GET http://api . domain. com/users/1234 查詢
PUThttp://api . domain. com/users/1234 修改
上例中用到了兩個HTTP方法，分別爲GET與PUT,它們的作用分別是獲取和更新指定資源，當請求方發起請求，修改了資源的狀態後，更新後的資源表述應返回給請求方，這也是表述性狀態傳遞的意義。
同時我們可以知道，REST是和HTTP有一定的關係，資源在服務的提供方和請求方之間進行傳遞。需要藉助於協議來約定，比如協議所規定的消息格式等，而HTTP協議則是非常成熟且廣泛使用的網絡協議。事實上，HTTP協議完全滿足REST中所定義的約束。因此，REST可以輕鬆的使用HTTP協議及其中的功能(如TTP方法，HTTP消息等)，並設計出鬆耦合的Web服務
REST約束
客戶端-服務端
客戶端-服務端約束體現了關注點分離原則，使客戶端與服務端各自能夠獨立實現並獨立開發，只要他們之間的接口不改變即可，客戶端可以使用不同的技術或編程語言。
統一接口
統一接口是設計任何RESTful服務的基礎，也是區別Rest風格與其他web服務風格的最主要體現，系統中多個組件（服務器，客戶端，以及可能存在的代理服務器等）都依賴統一接口，分別由4個子約束組成
資源標識
users/123,orders/12,docment/12
通過表述操作資源
格式通常爲json,xml，html等，最好是
json {user:{“id”:123,“name”:Tom}} xml 123Tom
自描述信息
客戶端和服務端之前傳遞的每一條消息都應包含足夠的信息，這些信息不僅包含了資源的表述，也包含了資源表述的相關信息（格式和內容長度），甚至包含了資源相關的其他操作信息。
超媒體作爲應用程序狀態引擎(HATEOAS)
服務器返回的資源表述中不僅要包含資源的表述，也應包含與之相關的鏈接，這些鏈接能夠對資源執行其他操作。比如當獲取資源時，返回的鏈接中，包含更新該資源，刪除資源等鏈接
分層系統
分層系統約束能夠使用網絡中介（如代理和網關）透明地部署到客戶端和服務端之間，只能能夠遵守並且使用前面提到的統一接口約束即可，客戶端和服務端都不知道網絡中介的存在。中間服務器主要用於增強安全，負載均衡和響應緩存等目的
緩存
緩存是web架構中重要的特性之一，客戶端和網絡中介均能夠緩存服務器返回的響應，因此當服務器返回響應時，應指明該響應的緩存特性，對響應進行緩存將有助於減少數據獲取延遲以及對服務器的請求，從而提高系統的性能。
無狀態
無狀態約束將指明服務器不會記錄或存儲客戶端的狀態信息，反之，這些狀態信息應有客戶端來保存並維護，因此客戶端對服務的請求不能依賴已發生的其他請求，當客戶端請求服務器時，必須在請求消息中包含所有與之相關的信息（如認證信息等）
按需編碼
按需編碼約束允許服務器臨時向客戶端返回可執行的程序代碼（如腳本等），返回這些代碼用戶爲客戶端提供擴展或自定義的功能，由於客戶端必須理解並能夠執行服務器返回的代碼，因此這一約束增加了客戶端和服務器之間的耦合，同時，這一約束是可選的 。
Restful api設計
對於REST及其約束，將有助於我們設計RESTful服務或Restful API,
在關注點方面 RESTful api 主要是面向資源，RPC 面向功能
在api斷點方面，REST 的端點是名詞，是資源或資源集合，而RPC的端點是動詞、是方法名
在執行特點方面，REST對資源執行操作，RPC執行服務器上的方法
在返回結果方面，REST返回請求的資源，而RPC則返回調用方法的執行結果
什麼是HTTP協議
超文本傳輸協議
1、URL 統一資源定義符
2、媒體類型
也就是說的內容類型，Content Type
3、http消息
也就是http之間交互的語言
3.1 起至行
3.2 HTTP消息頭
對於消息體的描述，和一些相關的配置
3.3 空行
3.4 HTTP消息體（資源，html表單）
4、http方法
GET POST PUT DELETE PATCH HEAD OPTIONS
GET 獲取資源
POST 創建資源
PUT 修改資源
DELETE 刪除資源
PATCH 資源部分更新 與 PUT 類似，但是是部分更新
HEAD 不會放回消息正文，和 GET類似
OPTIONS 方法用戶獲取資源支持的操作，
5、http消息頭
http請求頭
http響應頭
6、狀態碼
1XX : 信息
2XX : 成功
3XX ：重定向
4XX：客戶端錯誤
5XX：服務端錯誤
rest最佳實踐
原則：
1、使用名詞對的複數表示一個資源集合，如api.domain.com/users
2、使用斜線“/”用來表示資源之間的層次關係，如api.domain.com/users/1234/orders
3、對資源的增，刪，改，查等操作名稱不應包含在URL中，反之應正確使用HTTP方法，比如，GET/deleteuser/1234(錯誤)，DELETE users/1234(正確)
4、如果一個操作無法對應到資源的某個操作上，此時可以適當地在URI中包含動詞，但依然應該基於一個資源的標識符。例如：
PUT /users/1234/set-admin
DELETE /users/1234/set-admin
5、查詢字符串可以用來對資源進行篩選、搜索或分頁查詢等操作，如下所示
GET /users?role=admin
GET /users?searchQuery=abc
GET /users?pageSize=25&pageNumber=2
6、URI 中應儘量使用小寫字母
7、URI中可以使用中劃線“-”來增加其可讀性，如使用“-”來代替空格
http://api.domain.com/blogs/this-is-my-first-post
8、URI中不應使用下劃線
URI中通常會帶有下劃線，以表示它是可點擊的，這個下劃線將會使URI中下劃線不可見，可以使用“-”代替
9、URL末尾不應包含斜線“/”
例如：/users/1234/ 錯誤 /users/1234 正確
restful API資源標識格式
JSON和XML爲常用到的兩種資源表述格式，他們都可以用來傳遞數據，且都有簡潔，自描述的特點
restful api 版本
當api 發生了變化，比如資源表述內容有新增字段(字段或屬性)或系統添加了新資源類型時，應使用不同的版本來區別對API的更改，爲 restful api 添加版本有以下4方式
1、使用urI 路徑 如 api/v1/users
2、使用查詢字符串，如 api/users?version=v1
3、使用自定義消息頭，如Accept-version:v1
4、使用Accept消息頭，如Accept:application/json;v=2.0