REST参考手册
總說接口定義要遵守 RESTful，那么什么是REST呢，今天跟小編一起來了解一下這個規范吧~！
原文作者簡介：
BRIAN SLETTEN是一個關注前沿技術的軟件工程師，現居于加州奧本。他的職業生涯橫跨了各個行業，包括零售、銀行、網絡游戲、國防、金融、酒店和醫療保健。他擁有威廉瑪麗學院的計算機科學學士學位。BRIAN SLETTEN致力于Web架構、資源計算、社交網絡、語義網、數據科學、三維圖形、可視化、可伸縮系統、安全咨詢等第二十世紀末和第二十一世紀早期的技術。
引言
表述性狀態傳遞架構風格(Representational State Transfer)不是一項可購的技術，或者是一個在軟件開發項目中可以添加的庫。它是一種將信息提升為我們構建的架構的第一類元素的世界觀。 ?
我們用來描述“REST”系統的一些概念和術語參照了Roy Fielding博士的論文《基于網絡的軟件體系結構的架構風格與設計》(http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm)。盡管這是一篇學術論文，用詞十分正式，但是它仍然保留了通俗易懂的特點，為實踐提供了許多依據。
這些概念在我們稱之為Web的實現中得到了很好的證明。倡導RESTful風格在本質上來說，就是鼓勵組織在內部采用對外相同的原則。
基本概念
REST服務基于統一資源定位器（URL）。它能夠將指定資源與接受或返回的資源分開。URL方案在 RFC1738 (https://tools.ietf.org/html/rfc1738)中被定義。
對于某虛構的圖書館，它可能擁有一個如下所示的RESTful風格的API：??
http://fakelibrary.org/library
因此，被暴露的并不一定是某種服務，而是一種對用戶來說有價值的信息資源。實際上，URL用作資源的句柄，可以對資源進行請求、更新或刪除。 ?
首先我們要發布和這個虛擬圖書館進行RESTful風格交互的方法。RESTful的返回類型可以是XML,JSON或者是某種其他的超媒體格式，比如Atom或者用戶自定義的MIME類型。一般來說，我們要盡可能地復用現存的格式。但是，使用合理自定義的媒介的趨勢正在不斷增長。 ?
用戶可以使用一個超文本傳輸協議(HTTP)的GET方法來請求一個資源。比如說，在瀏覽器中輸入一個URL并點擊返回，選擇書簽，或者點擊一個錨引用鏈接。 ?
我們可以使用各種用戶端的API或者工具來與RESTful式的API進行交互。如果使用命令行的curl工具，我們可以輸入： ?
$ curl http://fakelibrary.org/library
在命令行上，返回的結果的形式是默認的。然而，我們并不想要這個形式的信息。所幸利用HTTP的機制，我們可以以不同的形式請求信息，可以在請求中指定一個“Accept”頭，如果服務器支持該請求，那么服務器就會將它返回到客戶端。根據下述格式再次使用curl： ?
$ curl –H "Accept:application/json" http://fakelibrary.org/library由于資源名與表單的分離，這種不同形式的信息請求方式是可行的。在REST中“R”指代的是“表示(representation)”而不是“資源(resource)”。在構建系統的時候要牢記這一點，我們要允許客戶以他們想要的形式請求信息。
?
我們的虛擬圖書館中可能包含的URL：
http://fakelibrary.org/library - 有關圖書館的大致信息，以及查找特定書籍、DVD等的鏈接的基準。
http://fakelibrary.org/book - 圖書的“信息空間”。從概念上講，它是所有可能的圖書的占位符。顯然，如果它是一個確定的值，我們就不能返回所有的書籍，但它可能會返回通過類別、關鍵字搜索等方式發現的圖書。
http://fakelibrary.org/book/category/1234 - 在書籍的信息空間里，我們可以想象以特定的類別（例如小說、兒童書籍、園藝等）來瀏覽它們。
http://fakelibrary.org/book/isbn/978-0596801687 - 指代某一個特定的書籍。它應該包括關于標題、作者、出版者、藏書量、余量等信息。
上述提到的URL對于用戶來說可能是只讀的，但是圖書館員可能會對這些資源進行操作。
舉例來說，我們可以向圖書的信息空間POST一個XML，來指代添加一本新的書籍。使用curl：
$ curl –u username:password -d @book.xml -H ? "Content-type: text/xml" http://fakelibrary.org/book此時，服務器可能會驗證結果，創建與本書相關聯的數據記錄，并返回“成功創建新資源”的201響應代碼。我們可以在響應頭中找到新資源的URL。
每一個RESTful請求都包含了足夠的狀態來回應請求。這滿足了服務器上的可見性與無狀態性，實現了系統的收縮性，并確定了正在執行的請求。這有助于實現結果的緩存。在結果集中，服務器的地址和請求的狀態組合在一起形成一個計算散列鍵(hash key)：
http://fakelibrary.org + /book/isbn/978-0596801687
由于GET請求的特性，它允許客戶端在必要情況下做出非常具體的請求。用戶可以在本地緩存結果，服務器可以緩存在遠程。另外，一些中間的體系結構也可以進行緩存。但是這并不意味著任何人都可以操作資源，可以設置一個保護模式，在用戶對資源進行操作之前，進行身份驗證。
關于SOAP
SOAP和REST經常被用于比較。許多人誤以為它們是等價的。實際上，他們是兩個不同的東西。這種錯誤認識主要源于人們認為“REST”是通過URL調用的Web服務。而事實上，REST是一種通過對信息的解耦來管理系統的方法。利用REST,我們可以實現：
高性能
可收縮性
通用性
簡化性
可修改性
可擴展性
這并不是說基于SOAP的系統不能擁有以上特性。但是，SOAP最適合的使用場景是，由于技術、組織或程序上的復雜性，導致請求的生命周期不能維持在單個事務范圍內的情況。
Richardson成熟度模型
Leonard Richardson引入了成熟度模型，用于在一定程度上闡明SOAP與REST之間的區別，并且提供了一個區分不同類型系統的框架。我們可以把這種分類看作測定一個系統所包含不同的Web技術的程度：信息資源、HTTP作為應用協議、超媒體作為控制媒介。
將其稱為“成熟模型”似乎意味著我們應該只在最成熟的級別上構建系統。其實不然，LEVEL2是有一定價值的，并且轉換到LEVEL3通常只需要采用一種新的MIME類型。即使提高ADOPTION會增加價值，但是從LEVEL0到LEVEL3的轉換仍然困難許多。
構建RESTful的流程是，首先確定想公開的信息資源，采用HTTP作為處理這些信息資源的應用程序協議，包括對內容協商的支持。然后，采用基于超媒體的MIME類型，你將體會到使用REST的所有優點。
RESTful中的動作詞匯
一般來說，初學者們對RESTful中經常出現的幾個動作詞匯感到十分困惑。這種看似絕對的約束，實際上旨在通過非特定的方式來鼓勵可預測的行為。通過明確地定義這些行為，用戶可以在面對網絡中斷和故障時自主地做出決定。以下是RESTful系統中4個主要的HTTP動作(有時也被叫做方法)：
GET
Web應用中最常見的動作，GET請求將指定的資源從服務器傳輸到客戶端。用戶不需要對他請求的資源有任何了解。它返回的是用元數據標記的字節碼，指示客戶端應如何解釋它。在
Web端，這通常是“文本/html”或“應用/xhtml+xml”。正如我們上面提到的，在使用內容協商的情況下，只要服務器允許，用戶就可以獲得所有請求的資源。 ?
GET請求最關鍵的特征之一是他不能修改任何服務器上的數據。它是一個絕對安全的請求。這也是初學REST的人常犯的錯之一。在上文提及的成熟度模型LEVEL1的系統中，我們經常可以看到這樣的URL：
http://example.com/res/action=update?data=1234
千萬不要這樣做！這是完全不符合RESTful的生態特性的。GET請求必須是安全的(不能修改任何數據)。
此外，GET請求也必須是冪等的。這意味著多次執行統一個請求總是得到相同的結果。這是在基于網絡的分布式系統中的一個非常重要的特性。如果客戶端在發出GET請求時被中斷，根據冪等性，該請求應該被再次發出。這是非常關鍵的一點，因為在一個設計良好的系統中，什么用戶從哪個應用發送請求是無關緊要的，應用總會做出特定的響應。但是我們越多地推進這種非特定于應用程序的行為，系統就越有彈性且易于維護。
POST
如果僅從動詞解釋的角度來看，POST和PUT確實沒有太大的差別，因為他們都可以表示創建或者更新資源。然而在RESTful系統中，他們是完全不同的。
在用戶無法確定他想創建的資源的屬性時，我們需要使用POST。例如，當我們下訂單，或者提交表單時，我們無法預測服務器會如何命名這些資源。這也是我們需要向服務器POST一個資源的指代(representation)的原因。服務器會對用戶的輸入進行接受、驗證等操作。如果這些操作都成功執行，那么服務器將會返回一個HTTP201響應。響應的頭中包含了新創建的資源的位置信息。
需要注意的是，有些人把POST看作一個對話式的GET請求。與一般情況下返回201狀態碼不同的是，他們會設置服務器返回一個200狀態碼，并將所創建的資源放入內容體。這看似是一個避免第二次請求的“捷徑”。但是，它將POST請求和GET請求合并在了一起，使資源的緩存變得復雜化。因此，請盡量避免以犧牲大局為代價去走這樣的“捷徑”。雖然短期看起來很方便，但這些“捷徑”會在將來給你帶來很大的麻煩。
POST的另外一個主要的用法是增補一個資源。這是一種增量編輯或者部分更新，而不是增加一個完整的新資源。舉例來說，對一個已知資源的POST部分更新可以是，添加一個送貨地址或者是修改購物車中商品的數量。
由于這種潛在的部分更新，POST不是一個安全、冪等的請求。
POST還被用在提交查詢上。查詢內容或者URL編碼的表單值會被提交給服務器來解釋查詢。因為查詢中沒有關聯標識，因此直接從這樣的POST請求返回的結果是合理的。
注意：可以考慮將一個查詢轉換成信息資源。一旦這樣的查詢被定義到了信息空間，我們就可以使用GET請求來獲取信息資源。同時我們也可以將這樣的鏈接分享給其他人。
PUT
因為HTML表單目前暫不支持PUT，許多開發人員在很大程度上忽略了這個請求。然而，它是RESTful系統中不可或缺的一環。用戶可以向已知URL發出PUT請求來完成對資源的重寫。不同于POST對資源的更新，PUT請求是冪等的。如果一個用戶在發送PUT請求時被中斷，由于冪等性，用戶完全可以重新提交一次該請求。
如果用戶可以預測資源的在服務器上的標識，那么PUT也可以用來新建資源。這種情況并不常見(原因參照上一節在POST中的討論)，但是如果用戶端控制著服務器端的信息空間，那么這樣做也是合理的。
DELETE
在公共的Web上，DELETE沒有被大量的使用。但是他依然是RESTful生態系統中重要的一環。
DELETE是冪等的。如果一個DELETE請求被網絡的故障打斷，用戶可以重新提交一次請求。不管第一次請求是否成功刪除了指定資源，用戶得到的響應都應該是204(內容不存在)。對于被刪除的資源或者從未存在的資源來說，追蹤他們可能需要一些額外的處理。出于安全考慮，對于已刪除或者從未存在的資源，我們應該返回404狀態碼，從而不泄漏任何信息。 ?
除了上文提到的4個常用的動作，還有另外三個不常用的動作，他們同樣重要。
HEAD
HEAD用于請求一個資源，但實際并不將它取回。這是客戶端檢查資源是否存在，并可能發現元數據的一種方式。
OPTIONS
OPTIONS可以通過詢問其他可用的請求，來向服務器詢問某個資源。
PATCH
PATCH是一種最新的HTTP方法，它只是在2010年初正式作為HTTP的一部分。它標準化的表達了對資源的部分更新。正如上文所說，POST可以在任何場所被使用，然而，沒有一個明確的規范來限制什么時候要將它用于部分更新。
標準格式的PATCH請求允許在交互中更明確地表示請求的意圖。IETF(國際互聯網工程任務組)提出了一些RFC(請求評議)來修補XML和JSON.
如果用戶提出了一個請求頭為If-Match的PATCH請求，那么該請求很有可能實現冪等，這意味著，該請求被意外中斷以后是可以重啟的。因為一旦該請求在第一次被成功執行，那么它的If-Match請求頭就會與新的狀態不同。如果他們相同，則代表第一次的請求未被成功執行，新的Patch請求將會被合理執行。
HTTP響應碼
HTTP的響應碼提供了關于用戶和服務器之間請求的詳細診斷信息。許多人僅僅熟悉幾個響應碼，比如200，403，404和500。事實上，實用的響應碼還有很多很多。下表列出了一些在RESTful環境下，開發者必須了解的響應碼。 ?
REST資源
參考論文
Fielding博士的論文。《基于網絡的軟件體系結構的架構風格與設計》(http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm)
一.RFC
定義REST技術規范由互聯網工程任務組（IETF）請求注釋（RFC）流程驅動。該規格給出了各個版本的版本號，并隨著時間的推移將現有的舊版本更新成新版本。目前，這是最新的請求注釋(RFC)。
URI
RFC3986包含了URI結構的命名方案。URI可以包括其他命名方案的編碼，如網站地址、命名空間、子方案等等。 ?
鏈接:[ietf.org/rfc/rfc3986.txt](ietf.org/rfc/rfc3986.txt)
URL
統一資源定位器（URL）是URI的一種形式。URL被嵌入了解析和定位資源(通常是訪問方案和地址)的信息。 ?
鏈接: [ietf.org/rfc/rfc1738.txt](ietf.org/rfc/rfc1738.txt)
IRI
國際化資源標識符（IRI）在概念上是以Unicode格式編碼的URI，以支持來自世界各地的語言的字符。IETF選擇創建一個新的標準，而不是改變URI方案本身，這樣可以在這兩種方法之間建立一個明確區分，同時不破壞現有的系統。IRI的支持者是故意為之的。因為存在一些使IRI和URI相互轉化的映射方案。 ?
鏈接：[ietf.org/rfc/rfc3987.txt](ietf.org/rfc/rfc3987.txt)
HTTP
超文本傳輸協議(HTTP)在1.1版本定義了一個應用程序協議，用于處理超媒體格式表示的信息資源。雖然它是一個應用程序級協議，但它通常不是特定于應用程序的，因此重要的架構效益應運而生。大多數人認為HTTP和超文本標記語言（HTML）就是“Web”，但是HTTP在開發面向非文檔的系統時也很有益處。 ?
鏈接：[ietf.org/rfc/rfc2616.txt](ietf.org/rfc/rfc2616.txt)
PATCH FORMATS
JavaScript Object Notation (JSON) Patch: ?
鏈接: [ietf.org/rfc/rfc6902.txt](ietf.org/rfc/rfc6902.txt) ?
XML Patch Site: ?
鏈接: [ietf.org/rfc/rfc7351.txt](ietf.org/rfc/rfc7351.txt)
描述語言
人們熱衷于用語言來描述API，以便更容易地為客戶機和服務器編寫文檔，甚至可能生成框架。下面描述一些較流行或有趣的語言：
RAML
一種用于描述面向LEVEL2的API的YAML/JSON語言。它包括對可重用模式的支持，這個特性有助于標準化API的功能設計。 ?
鏈接: [raml.org](raml.org)
SWAGGER
另一種用于描述面向LEVEL2的API的YAML/JSON語言。它包括代碼生成器、編輯器、API文檔的可視化以及與其他服務集成的能力。它是開放API戰略的基礎。 ?
鏈接: [swagger.io](swagger.io) 和 [swagger.io](swagger.io)
APIARY.IO
一個協作的托管站點，支持基于Markdown的API文檔，圍繞設計過程進行的交互，以及對模擬托管實施的支持，以便在實施之前輕松測試API。 ?
鏈接: [apiary.io](apiary.io)
HYDRA-CG
它是一種超媒體描述語言。它通過某些標準(比如json-ld)，使得自己對數據鏈接的支持、與其他數據源的交互更為容易。 ?
鏈接: [hydra-cg.com](hydra-cg.com)
二.實際應用
有幾個庫和框架可用于構建生成和使用REST系統的系統。
現在有許多庫和框架可構建使用RESTful的系統。雖然任何Web服務器都可以配置REST API，但使用這些框架和庫更為方便。下面是一些主要環境的概述：
JAX-RS:
該規范增加了JEE對REST的支持。 ?
鏈接: [jax-rs-spec.java.net](jax-rs-spec.java.net)
RESTLET:
Restlet API是在RESTful系統上建立Java API的先期嘗試之一。他的重點在于建立一套在用戶端和服務器端功能對等的既簡明而又功能強大的API。Restlet Studio是一款免費的工具，他允許RAML和基于Swagger的API之間的轉換，同時支持Restlet, Node和JAX-RS。 ?
鏈接：[restlet.org](restlet.org)
NETKERNEL:
NetKernel是一套非常有意思的RESTful系統，他支持各種架構風格的微核環境。它得益于在軟件體系結構中采用Web的經濟學特性。你可以認為他是一種“引進的REST”。然而，RESTful的系統在外部看起來相差都不大，NetKernel也是如此。 ?
鏈接: [netkernel.org](netkernel.org)
PLAY:
當前有兩個主要的Scala語言REST框架。PLAY就是其中之一。 ?
鏈接:[playframework.com](playframework.com)
SPRAY:
另外一個Scala語言REST框架。主要運作于Akka模式。 ?
鏈接: [spray.io](spray.io)
EXPRESS:
Node.js的REST框架。 ?
鏈接: [expressjs.com](expressjs.com)
HAPI:
另一個Node.js的REST框架。 ?
鏈接: [hapijs.com](hapijs.com)
SINATRA:
Ruby的RESTful框架。 ?
鏈接: [sinatrarb.com](sinatrarb.com)
三.客戶端工具
我們的確可以使用瀏覽器來調用REST，但是在創建和測試面向資源的系統中，使用一些客戶端工具是更為方便和高效的。
CURL:
CURL是一種廣受歡迎的命令行工具，它可以調用各種資源上的各種協議。 ?
鏈接: [curl.haxx.se](curl.haxx.se)
HTTPIE:
HTTPIE是一款非常靈活，易于使用的客戶端工具。它通過HTTP進行資源的交互。
鏈接: [httpie.org](httpie.org)
POSTMAN:
POSTMAN是一款全面的API測試工具。它可以捕獲和重置各種請求，使用各種授權認證。一些早期的命令行工具也可以實現需要的大部分功能，但是POSTMAN作為一款全新的桌面應用，他大大的降低了開發者的工作量，提高了工作效率。 ?
原文地址：https://dzone.com/refcardz/rest-foundations-restful
.NET社區新聞，深度好文，微信中搜索dotNET跨平臺或掃描二維碼關注
總結
- 上一篇： DotNetCore跨平台~Docker
- 下一篇： Docker~从Dockerfile到C