一、請求--響應(yīng)API

請求--響應(yīng)類的API的典型做法是，通過基于HTTP的Web服務(wù)器暴露一個/套接口。API定義一些端點，客戶端發(fā)送數(shù)據(jù)的請求到這些端點，Web服務(wù)器處理這些請求，然后返回響應(yīng)。響應(yīng)的格式通常是JSON或XML。

在這種類型的Web API里，比較流行的是這三種：REST，RPC和GraphQL。?

1.1 REST

REST全稱是Representational State Transfer?表述性狀態(tài)傳遞。REST可能是現(xiàn)在最流行的一種Web API。

REST的核心就是資源，一個資源就是可以被標(biāo)識的實體，它有名稱和地址。

REST API就是把數(shù)據(jù)以資源的形式暴露出來，并使用標(biāo)準(zhǔn)的HTTP方法來代表創(chuàng)建、讀取、更新和刪除資源等事務(wù)。

?

REST API有一些規(guī)則和約束，這里我就簡單的寫一下（之前的文章有詳細(xì)描述）：

• 資源都是URL的一部分，例如/persons

• 針對每個資源通常都會有兩個URL被實現(xiàn)：“/persons”表示資源的集合，“/person/321”表示特定的一個資源

• 在資源里，使用名詞而不是動詞，例如 /getUserInfo/123 這就不對了，應(yīng)該是 /users/123

• HTTP方法表明了要執(zhí)行的動作，不同的HTTP方法作用于同一個URL上可實現(xiàn)不同的功能：

  • 創(chuàng)建 -- POST

  • 讀取 -- GET

  • 整體更新 -- PUT

  • 局部更新 -- PATCH

  • 刪除 -- DELETE

• ? 服務(wù)器會返回標(biāo)準(zhǔn)的HTTP狀態(tài)碼，來表示請求成功或者失敗，以及原因。通常2xx表示成功，3xx表示資源被移動了，4xx表示客戶端引起的錯誤，5xx表示服務(wù)器端引起的錯誤。

?

如果兩個資源有主從關(guān)系，那么子資源最好不采用頂級資源的URL，而是采用主資源的子資源URL地址。例如Province和City就是主從關(guān)系，那么City資源的URL應(yīng)該是：/provinces/{provinceId}/cities，/provinces/{provinceId}/cities/{cityId}

?

非CRUD操作

API難免會有一個非CRUD的操作，例如“存檔”這個操作。這時候我們可以采取以下幾種辦法：

• 把這個動作作為資源的一個字段。例如把“存檔”作為輸入?yún)?shù)傳遞到API

• 作為子資源。例如 /repos/{repoId}/issues/{issueId}/archive

• 直接使用動詞。實在不行了，就用動詞吧，例如 /search/params?......

?

1.2 RPC

Remote Procedure Call。RPC是一種比較簡單的API，客戶端直接會執(zhí)行另一個服務(wù)器上的代碼。

REST是關(guān)于資源的，而RPC就是關(guān)于動作的。

在RPC里，客戶端通常是把方法名和參數(shù)傳遞給服務(wù)器，然后服務(wù)器返回JSON或XML。

?

RPC的規(guī)則比較少：

• 端點要包含被執(zhí)行操作的名字

• 使用合理的HTTP動詞，GET用于讀取，POST用于其它類型。?

RPC適用于那種無法用CRUD封裝的動作，或者其影響和資源無關(guān)的動作。?

RPC不僅限于HTTP，還有其它協(xié)議可以支持，例如Apache Thrift和gRPC。

?

1.3 GraphQL

GraphQL 是 API的查詢語言。最近越來越火。它由Facebook于2012年開始開發(fā)，2015年被開源了。

?

GraphQL允許客戶端定義需要得到的數(shù)據(jù)結(jié)構(gòu)，服務(wù)器精確的返回所需的數(shù)據(jù)結(jié)構(gòu)，例如：

?

?

與REST和RPC不同，GraphQL API只需要一個端點；它也不需要使用不同的HTTP動詞，它只使用POST，你需要在JSON body里面指定是要執(zhí)行查詢還是修改。

?

相對REST和RPC，GraphQL有下面幾個優(yōu)勢：

• 節(jié)省了多重的請求往返，GraphQL可以一次把所需的關(guān)聯(lián)數(shù)據(jù)全部查詢出來。不會存在例如N+1這樣的問題

• 避免了API版本問題。你可以隨時添加字段和類型，不會影響現(xiàn)有的查詢。可以標(biāo)記棄用。通過Log可以追蹤出哪些字段被誰使用，如果字段沒人再去使用，就可以移除它了。

• Payload比較小。REST和RPC的響應(yīng)都包含客戶端發(fā)送一些不需要的數(shù)據(jù)。而使用GraphQL的話，客戶端得到的響應(yīng)就是它所請求的那些東西，不多不少。

• 強類型。GraphQL是強類型的，開發(fā)時有類型檢查能保證查詢的正確性和合理性。

• 內(nèi)省(Introspection)。像REST，就需要安裝Swagger等工具來幫助瀏覽API。而GraphQL本身就具備可發(fā)現(xiàn)性。它還帶有一個瀏覽器內(nèi)的IDE用來瀏覽GraphQL API。下圖就是Github的GraphQL API：

?

?

GraphQL的缺點就是它為服務(wù)器添加了許多復(fù)雜性，服務(wù)器需要額外的工作來處理這些復(fù)雜的查詢。根據(jù)查詢內(nèi)容的不同，性能也是一個變數(shù).

?

綜上所述，那么什么時候應(yīng)該用哪種Web API呢？

• 針對CRUD類的API，使用REST

• 針對暴露很多動作的API，使用RPC

• 當(dāng)你需要查詢的靈活性以及維護的連續(xù)性時，使用GraphQL

?

二、事件驅(qū)動式 Web API

針對用請求-響應(yīng)式API，如果服務(wù)的數(shù)據(jù)經(jīng)常變化，那么響應(yīng)就可能無法保持新鮮了。開發(fā)者如果想與變化的數(shù)據(jù)保持同步，就只能對API進(jìn)行polling操作了。

但是如果poll的頻率較低，客戶端仍有可能無法獲得從上次poll到現(xiàn)在所有的數(shù)據(jù)事件。如果poll的頻率較高，還特別浪費資源。?

所以我們需要實時的分享事件的數(shù)據(jù)，通常使用下面三種機制：WebHook，WebSocket，HTTP Streaming。?

2.1?WebHooks

WebHook就是一個接收HTTP POST（或GET，PUT，DELETE）的URL。一個實現(xiàn)了WebHook的API提供商就是在當(dāng)事件發(fā)生的時候會向這個配置好的URL發(fā)送一條信息。與請求-響應(yīng)式不同，使用WebHook，你可以實時接受到變化。

?

下面是Polling和Webhook的比較：

?

WebHook非常適合于從一個服務(wù)器向另外一個服務(wù)器分享實時數(shù)據(jù)。

?

但是實現(xiàn)WebHook，也引入了新的復(fù)雜性：

• 失敗和重試。為了保證WebHook被成功的傳輸，你需要構(gòu)建一個可以再發(fā)生錯誤時進(jìn)行重試操作的系統(tǒng)。

• 安全性。對于安全的調(diào)用REST API，現(xiàn)在的方案都比較成熟；而對于WebHook來說，這方面依然在探索中前進(jìn)。

• 防火墻。防火墻后運行的應(yīng)用可以通過HTTP訪問API，但是它們可能無法接收入站的流量。所以這是一個很大的問題。

• 噪聲。通常每個WebHook調(diào)用代表了一個事件，但當(dāng)短時間內(nèi)發(fā)生了成千上萬個事件的時候，再通過WebHook來傳輸，就可能會有噪音。

?

2.2?WebSocket

WebSocket這個協(xié)議，它通過一個TCP協(xié)議建立一個雙向全雙工的流式通信。WebSocket通常用在客戶端和服務(wù)器之間的通信，也可以用在服務(wù)器之間的通信。

ASP.NET Core SignalR就是優(yōu)先使用該協(xié)議。

?

WebSocket支持全雙工（服務(wù)器和客戶端可以同時雙向通信），而且開銷不高。經(jīng)常使用的端口式80或443，這樣就很容易穿過防火墻了。

?

WebSocket特別適合于快速的，現(xiàn)場的路i數(shù)據(jù)和長連接。

如果連接掛掉了，客戶端會嘗試重新初始化連接。但是WebSocket有一些擴展性的問題，因為如果在線的客戶端太多，那么服務(wù)器端就需要維持這些客戶端打開的連接。

?

2.3?HTTP Streaming

使用請求-響應(yīng)式API，客戶端發(fā)送一個請求，服務(wù)器端返回一個響應(yīng)，這個響應(yīng)的長度是有限的。

而使用HTTP Streaming，服務(wù)器端可以在一個由客戶端打開的長生存的連接里持續(xù)的推送新數(shù)據(jù)。

?

為了讓數(shù)據(jù)通過一個可長時間存在的連接上進(jìn)行傳輸，有兩個方案：

• 首先可以讓服務(wù)器把Transfer-Encoding這個Header設(shè)為chunked。這表示客戶端是按塊接收數(shù)據(jù)的，塊與塊之間用換行符分割：“\r\n”。

• 另一個選項是通過Server-Sent Events (SSE)來進(jìn)行流數(shù)據(jù)。這個比較適合于瀏覽器內(nèi)的客戶端，因為這樣它們就可以使用標(biāo)準(zhǔn)的EventSource API了。（SignalR在無法使用WebSocket的時候就會使用SSE）

?

HTTP Streaming用起來好像很容易，但是有個問題，是關(guān)于緩存的。客戶端和代理經(jīng)常會有緩存的限制。因為只有達(dá)到某個閾值之后，它們才會把數(shù)據(jù)渲染給應(yīng)用。??

綜上，針對事件驅(qū)動式Web API：

• 如果想要進(jìn)行服務(wù)器間的實時事件通信，可以選擇WebHooks

• 如果需要瀏覽器和服務(wù)器間的雙向?qū)崟r通信，可以選擇WebSocket

• 如果需要使用簡單的HTTP進(jìn)行單向通信，可以使用HTTP Streaming

原文地址：https://www.cnblogs.com/cgzl/p/9786801.html

.NET社區(qū)新聞，深度好文，歡迎訪問公眾號文章匯總 http://www.csharpkit.com

總結(jié)

以上是生活随笔為你收集整理的常见形式 Web API 的简单分类总结的全部內(nèi)容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網(wǎng)站內(nèi)容還不錯，歡迎將生活随笔推薦給好友。