如何更好的設(shè)計RESTful API

作者：知秋z 2016-12-30 14:47:21

構(gòu)建API是您可以做的最重要的事情之一，以提高您的服務(wù)的價值。通過使用API，您的服務(wù)/核心應(yīng)用程序有可能成為其他服務(wù)增長的平臺。看看當前巨大的科技公司：Facebook，Twitter，谷歌，GitHub，亞馬遜，Netflix …沒有一個人會像今天一樣大，如果他們沒有通過API打開他們的數(shù)據(jù)。事實上，整個行業(yè)存在的唯一目的是消費由所述平臺提供的數(shù)據(jù)。

當您的數(shù)據(jù)模型已開始穩(wěn)定，您可以為您的網(wǎng)絡(luò)應(yīng)用程序創(chuàng)建公共API。你意識到，很難對你的API進行重大更改，一旦它發(fā)布，并希望盡可能得到盡可能多的前面。現(xiàn)在，互聯(lián)網(wǎng)對API設(shè)計的意見有很多。但是，因為沒有一個廣泛采用的標準在所有情況下都有效，所以你前面有一堆選擇：你應(yīng)該接受什么格式？你應(yīng)該如何認證？你的API是否應(yīng)該版本化？構(gòu)建API是您可以做的最重要的事情之一，以提高您的服務(wù)的價值。通過使用API，您的服務(wù)/核心應(yīng)用程序有可能成為其他服務(wù)增長的平臺。看看當前巨大的科技公司：Facebook，Twitter，谷歌，GitHub，亞馬遜，Netflix …沒有一個人會像今天一樣大，如果他們沒有通過API打開他們的數(shù)據(jù)。事實上，整個行業(yè)存在的唯一目的是消費由所述平臺提供的數(shù)據(jù)。

你的API越簡單明了，使用的人就越多。

許多在網(wǎng)絡(luò)上發(fā)現(xiàn)的API設(shè)計觀點是圍繞主觀的模糊標準解釋的學術(shù)討論，而不是在現(xiàn)實世界中有意義的。我的目標是描述一個為當今的Web應(yīng)用程序設(shè)計的務(wù)實的API的***實踐。我沒有嘗試滿足一個標準，如果它不覺得正確。為了幫助指導決策過程，我寫了一些API必須努力達到的要求：

它應(yīng)該使用Web標準，他們有意義
它應(yīng)該對開發(fā)人員友好，可以通過瀏覽器地址欄探索
它應(yīng)該簡單，直觀和一致，使采用不僅容易，而且愉快
它應(yīng)該提供足夠的靈活性來支持大部分我們所設(shè)計的UI
應(yīng)該是有效的，同時保持與其他要求的平衡

API是開發(fā)人員的UI – 就像任何UI一樣，確保用戶的體驗被仔細考慮是非常重要的！

RESTful API設(shè)計定義

以下是我將在本文檔中使用的一些重要術(shù)語：

Resource ：對象的單個實例。例如，一只動物。
集合：對象的集合。例如，動物。
HTTP ：用于通過網(wǎng)絡(luò)通信的協(xié)議。
Consumer ：能夠發(fā)出HTTP請求的客戶端計算機應(yīng)用程序。
第三方開發(fā)人員：不是您項目的一部分，但希望使用您的數(shù)據(jù)服務(wù)的開發(fā)人員。
服務(wù)器：可通過網(wǎng)絡(luò)從客戶端訪問的HTTP服務(wù)器/應(yīng)用程序。
端點：服務(wù)器上的API網(wǎng)址，表示資源或整個集合。
冪等：無邊際效應(yīng)，多次操作得到相同的結(jié)果。
網(wǎng)址區(qū)段：網(wǎng)址中的斜線分隔的信息。

數(shù)據(jù)設(shè)計和抽象

首先將從你寫的開發(fā)文檔API開始(比如我們可以看到各個開發(fā)平臺的暴露出來的API文檔)，您需要決定如何設(shè)計數(shù)據(jù)，以及您的核心服務(wù)/應(yīng)用程序如何工作。如果你在做的API是***次開發(fā)，這應(yīng)該很容易。如果您要將API附加到現(xiàn)有項目，則可能需要提供更多抽象(畢竟是要按照已有的文檔規(guī)范來做)。

有時，集合可以表示數(shù)據(jù)庫表，資源可以表示該表中的一行。然而，這不是通常的情況。事實上，你的API應(yīng)該盡可能多地抽象出你的數(shù)據(jù)和業(yè)務(wù)邏輯。非常重要的一點是，如果您不希望使用你的API很難使用，就不要使用任何復雜的應(yīng)用程序數(shù)據(jù)來為難第三方開發(fā)人員(讓開發(fā)人員覺得還得對這些數(shù)據(jù)進一步處理而浪費更多精力)。

還有你的服務(wù)的很多部分，你不應(yīng)該通過API公開。一個常見的例子是許多API不允許第三方創(chuàng)建用戶。

設(shè)計資源請求

當然你知道GET和POST請求。當您的瀏覽器訪問不同的網(wǎng)頁時，這兩個最常用的請求。POST是如此受歡迎，它甚至流行語我們的平常的說話中，即使那些不知道互聯(lián)網(wǎng)如何工作的人也知道他們可以“發(fā)布”的東西在朋友的Facebook上。

有四個半非常重要的HTTP動詞，你需要知道。我說“一半”，因為PATCH動詞非常類似于PUT動詞，兩個通常由許多API開發(fā)人員組合。這里是動詞，在他們旁邊是他們相關(guān)的數(shù)據(jù)庫調(diào)用（我假設(shè)大多數(shù)人讀這個知道更多關(guān)于寫入數(shù)據(jù)庫而不是設(shè)計一個API）。

GET （SELECT）：從服務(wù)器檢索特定資源，或資源列表。
POST （CREATE）：在服務(wù)器上創(chuàng)建一個新的資源。
PUT （UPDATE）：更新服務(wù)器上的資源，提供整個資源。
PATCH （UPDATE）：更新服務(wù)器上的資源，僅提供更改的屬性。
DELETE （DELETE）：從服務(wù)器刪除資源。

這里有兩個較少知名的HTTP動詞：

HEAD - 檢索有關(guān)資源的元數(shù)據(jù)，例如數(shù)據(jù)的哈希或上次更新時間。
OPTIONS - 檢索關(guān)于客戶端被允許對資源做什么的信息。

一個好的RESTful API將使用四個半HTTP動詞，允許第三方與其數(shù)據(jù)進行交互，并且不會將動作/動詞作為URL段。

通常，GET請求可以被緩存（通常是！）在瀏覽器，例如將緩存請求頭用于第二次用戶的POST請求。 HEAD請求基本上是一個沒有響應(yīng)主體的GET，并且也可以被緩存。

版本控制

無論你正在構(gòu)建什么，無論你事先做了多少規(guī)劃，你的核心應(yīng)用程序總會改變，你的數(shù)據(jù)關(guān)系總會改變，屬性添加和從你的資源中刪除。這只是軟件開發(fā)的工作原理，尤其是如果你的項目還活著并被許多人使用（如果你正在構(gòu)建一個API，情況可能就會如此）。

記住，API是服務(wù)器和客戶端之間的已發(fā)布約定。如果您更改了服務(wù)器API，這些更改會破壞向后兼容性，那么你就打破了這個約定，客戶端又會要求你重新支持它(誰讓客戶端依然是之前的版本，調(diào)用的還是之前的API)。為了避免這樣的事情，并讓您的客戶端滿意，您需要偶爾引入新版本的API，同時仍允許訪問舊版本。

注意，如果你只是為你的API添加新的特性，例如資源上的新屬性，或者如果你添加新的端點(比如之前只有查詢，現(xiàn)在增加一個修改)，你不需要增加您的API版本號，因為這些更改不會破壞向后兼容性。當然，您將需要更新您的API文檔。

隨著時間的推移，您可以棄用API的舊版本。棄用某個功能并不意味著關(guān)閉它或者降低它的質(zhì)量，而是告訴客戶端您的API，舊版本將在特定日期刪除，并且他們應(yīng)該升級到較新的版本。

一個好的RESTful API設(shè)計將跟蹤URL中的版本。另一個最常見的解決方案是將版本號放在請求頭中，但在與許多不同的第三方開發(fā)人員合作之后，我可以告訴您，添加這些請求頭信息并不像添加網(wǎng)址細分那么容易。

分析

跟蹤客戶端使用的API的版本/端點。這可以像每次請求時在數(shù)據(jù)庫中增加一個整數(shù)一樣簡單。有很多原因跟蹤API Analytics是一個好主意，例如，最常用的API調(diào)用應(yīng)該是高效的。

為了構(gòu)建第三方開發(fā)者所喜歡的API，最重要的是，當您棄用某個版本的API時，實際上可以使用已棄用的API功能與開發(fā)人員聯(lián)系(在兩個異構(gòu)系統(tǒng)中當對方的開發(fā)人員調(diào)用本服務(wù)時順帶告知對方)。這是提醒他們在棄用舊API版本之前升級的***方法。

第三方開發(fā)者通知的過程可以自動化，例如。每當對一個已棄用的功能發(fā)出10,000個請求時，發(fā)郵件通知開發(fā)人員。

API Root URL

無論你相信與否，您的API的根位置是重要的。當開發(fā)人員使用您的API接手舊項目并需要構(gòu)建新功能時，他們可能根本不知道您有哪些服務(wù)。幸好他們知道客戶端對外調(diào)用的那些URL列表。重要的是，進入您的API的根入口點盡可能簡單，因為長的復雜URL將顯得令人生畏，并可能使開發(fā)人員直接略過而不會采用。

這里有兩個常見的URL根：

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

如果您的應(yīng)用程序龐大，或者您預計它會變得龐大，將API放在自己的子域（例如 api。）上是一個不錯的選擇。這可以允許在路上一些更靈活的可擴展性。

如果您預計您的API將不會增長到那么大，或者您想要一個更簡單的應(yīng)用程序設(shè)置（例如，您希望從同一個框架托管網(wǎng)站和API），將您的API放置在域根的URL段（例如 / api / ）也有效。

將內(nèi)容設(shè)為您的API根目錄是個好主意。例如，點擊GitHub的API的根會返回一個端點列表。就個人而言，我喜歡使用根網(wǎng)址提供給開發(fā)人員認為有用的信息，例如，如何獲取API的開發(fā)人員文檔。

此外，請注意HTTPS前綴。作為一個好的RESTful API，您必須在HTTPS之后托管您的API(一個好的RESTful API總是基于HTTPS來發(fā)布的)。

端點

端點是您的API中指向特定資源或資源集合的URL。

如果你正在構(gòu)建一個虛擬的API來代表幾個不同的動物園，每個動物園包含許多動物，員工（可以在多個動物園工作）和跟蹤每個動物的物種，你可能有以下端點：

https://api.example.com/v1/**zoos**
https://api.example.com/v1/**animals**
https://api.example.com/v1/**animal_types**
https://api.example.com/v1/**employees**

當引用每個端點可以做什么時，您需要列出有效的HTTP動詞和端點組合。例如，這里有一個半全面的行動列表，可以使用我們虛構(gòu)的API執(zhí)行。請注意，我在每個端點之前都有HTTP動詞，因為這是在HTTP請求標頭中使用的相同符號。

GET / zoos：列出所有動物園（ID和名稱，不要太多細節(jié)）
POST / zoos：創(chuàng)建一個新的Zoo
GET / zoos / ZID：檢索整個Zoo對象
PUT / zoos / ZID：更新Zoo（整個對象）
PATCH / zoos / ZID：更新Zoo（部分對象）
DELETE / zoos / ZID：刪除動物園
GET / zoos / ZID / animals：檢索動物列表（ID和名稱）。
GET / animals：列出所有動物（ID和名稱）。
POST / animals：創(chuàng)建一個新的動物
GET / animals / AID：檢索動物對象
PUT / animals / AID：更新動物（整個對象）
PATCH / animals / AID：更新動物（部分對象）
GET / animal_types：檢索所有動物類型的列表（ID和名稱）
GET / animal_types / ATID：檢索整個動物類型對象
GET / employees：檢索完整的員工列表
GET / employees / EID：檢索特定員工
GET / zoos / ZID / employees：檢索在此動物園工作的員工（ID和名稱）的列表
POST / employees：創(chuàng)建一個新員工
POST / zoos / ZID / employees：在特定動物園雇用員工
DELETE / zoos / ZID / employees / EID：從特定的動物園中解雇員工

在上面的列表中，ZID表示Zoo ID，AID表示動物ID，EID表示Employee ID，ATID表示動物類型ID。在你的文檔中有一個鍵，你選擇的任何約定是一個好主意。

為了簡潔，我在上面的示例中省略了常見的API網(wǎng)址前綴。雖然這在通訊期間可能很好，但在實際的API文檔中，您應(yīng)該始終顯示每個端點的完整網(wǎng)址（例如GET http://api.example.com/v1/animal_type/ATID）。

注意數(shù)據(jù)之間的關(guān)系如何顯示，特別是雇員和動物園之間的多對多關(guān)系。通過添加其他網(wǎng)址細分，您可以執(zhí)行更具體的互動。當然，對于“FIRE(解雇)”沒有HTTP動詞，但是通過對位于Zoo內(nèi)的Employee執(zhí)行DELETE，我們能夠?qū)崿F(xiàn)相同的效果。

過濾器

當客戶端請求對象列表時，請務(wù)必為它們提供符合所請求條件的每個對象的列表。這個列表可能是巨大的。但是，重要的是不要對數(shù)據(jù)執(zhí)行任何任意限制。正是這些任意的限制使第三方開發(fā)者很難知道發(fā)生了什么。如果他們請求某個集合，并迭代結(jié)果，他們從來沒有看到超過100個結(jié)果，接下來他們就不得不去查找這個限制條件的出處(提供服務(wù)端沒有問題，就只能是調(diào)用端的問題了)。到底是他們的ORM的bug導致的，還是因為網(wǎng)絡(luò)截斷了大數(shù)據(jù)包？

盡可能減少那些會影響到第三方開發(fā)者開發(fā)的無謂限制

然而，重要的是，您確實為客戶端提供了指定某種過濾/結(jié)果限制的能力。這么做最重要的一個原因是可以最小化網(wǎng)絡(luò)傳輸，客戶端盡快得到結(jié)果。第二個重要的原因是客戶端可能是懶惰的，如果服務(wù)器可以為他們做過濾和分頁，一切都更好。還有一個不那么重要的原因，請求資源越少，對服務(wù)器的一個很大的好處是，減少了負載。

過濾主要用于對資源集合執(zhí)行GET。由于這些是GET請求，因此應(yīng)通過URL傳遞過濾信息。以下是您可能想要添加到API的過濾類型的一些示例：

?limit = 10:減少返回給Consumer的結(jié)果數(shù)（用于分頁）
?offset = 10:向客戶端發(fā)送信息集（用于分頁）
?animal_type_id = 1:過濾符合以下條件的記錄（WHERE animal_type_id = 1）
?sortby = name&order = asc:根據(jù)指定的屬性對結(jié)果進行排序（ORDER BYname ASC）

其中一些過濾可能與端點URLS冗余。例如我之前提到的GET / zoo / ZID / animals。這與GET / animals是一樣的嗎？zoo_id = ZID。為客戶端提供的專用端點將使他們的開發(fā)更輕松，這對于您預期他們會做很多的請求尤其如此。在文檔中，提及這種冗余，以便第三方開發(fā)人員不會留意是否存在差異。

還有一個要說的是，每當您執(zhí)行數(shù)據(jù)的過濾或排序時，請確保您列出客戶端可以過濾和排序的列。我們不希望將任何數(shù)據(jù)庫錯誤發(fā)送給客戶端！

狀態(tài)碼

作為RESTful API，使用正確的HTTP狀態(tài)代碼非常重要;他們是一個標準！各種網(wǎng)絡(luò)設(shè)備能夠讀取這些狀態(tài)碼，例如，負載平衡器可以配置為避免向發(fā)送大量50x錯誤的Web服務(wù)器發(fā)送請求。有很多HTTP狀態(tài)代碼可供選擇，但此列表應(yīng)該是一個很好的起點：

200 OK – [GET]
客戶端從服務(wù)器請求數(shù)據(jù)，服務(wù)器為它們找到它（等冪）
201 CREATED – [POST / PUT / PATCH]
客戶端提供了服務(wù)器數(shù)據(jù)，并且服務(wù)器創(chuàng)建了一個資源
204 無內(nèi)容 – [刪除]
客戶端要求服務(wù)器刪除資源，并且服務(wù)器將其刪除
400 無效請求 – [POST / PUT / PATCH]
客戶端給服務(wù)器的數(shù)據(jù)不良，服務(wù)器沒有做任何事情（冪等）

*錯誤404 – []

*客戶端引用了一個不存在的資源或集合，并且服務(wù)器什么也不做（冪等）

*500內(nèi)部服務(wù)器錯誤 – []

*服務(wù)器遇到錯誤，并且客戶端不知道請求是否成功

狀態(tài)碼范圍

1xx 范圍保留用于底層HTTP的東西，你很可能永遠也用不到。

2xx 范圍保留用于成功消息，盡可能確保您的服務(wù)器盡可能多地向客戶端發(fā)送這些消息。

3xx 范圍保留用于重定向。大多數(shù)API不使用這些請求很多（不像SEO人使用它們那么頻繁），然而，較新的超媒體風格API將更多地使用這些請求。

4xx 范圍保留用于響應(yīng)客戶端做出的錯誤，例如。他們提供不良數(shù)據(jù)或要求不存在的東西。這些請求應(yīng)該是冪等的，而不是更改服務(wù)器的狀態(tài)。

5xx 范圍的狀態(tài)碼是保留給服務(wù)器端錯誤用的。這些錯誤常常是從底層的函數(shù)拋出來的，甚至開發(fā)人員也通常沒法處理，發(fā)送這類狀態(tài)碼的目的以確保客戶端獲得某種響應(yīng)。當收到5xx響應(yīng)時，客戶端不可能知道服務(wù)器的狀態(tài)，所以這類狀態(tài)碼是要盡可能的避免。

預期的返回文檔

當使用不同的HTTP動詞對服務(wù)器端點執(zhí)行操作時，客戶端需要在返回結(jié)果里面拿到一系列的信息。下面的列表是非常典型的RESTful API：

GET / collection：返回資源對象的列表（數(shù)組）
GET / collection / resource：返回單個Resource對象
POST / collection：返回新創(chuàng)建的Resource對象
PUT / collection / resource：返回完整的Resource對象
PATCH / collection / resource：返回完整的Resource對象
DELETE / collection / resource：返回一個空文檔

請注意，當Consumer創(chuàng)建資源時，他們通常不知道正在創(chuàng)建的資源的ID（也不知道其他屬性，如創(chuàng)建和修改的時間戳）（如果適用）。這些附加屬性與后續(xù)請求一起返回，當然作為對初始POST的響應(yīng)。

###認證

大多數(shù)時候，一個服務(wù)器想要知道誰正在做哪些請求。當然，一些API提供公共用戶(匿名用戶)使用的，但大多數(shù)時間的工作是代表某人執(zhí)行。

OAuth 2.0提供了一個很好的方法。對于每個請求，您可以確定知道哪個客戶正在發(fā)出請求，代表他們請求哪個用戶，并提供一種（大部分）標準化的方式來過期訪問或允許用戶撤消來自客戶端的訪問權(quán)，需要第三方客戶端知道用戶登錄憑據(jù)。

還有OAuth 1.0和xAuth同樣適用這樣的場景。無論您選擇哪種方法，請確保它是常見的，并且有許多不同的庫為您的客戶端可能使用的語言/平臺編寫的文檔(比如redis提供Java調(diào)用的API)。

我可以誠實地告訴你，OAuth 1.0a，雖然它是最安全的選項，但是實現(xiàn)起來很痛苦。建議你選擇一個替代品。

內(nèi)容類型

目前，最令人興奮的API提供來自RESTful接口的JSON數(shù)據(jù)。這包括Facebook，Twitter，GitHub，你命名。 XML似乎已經(jīng)失去了優(yōu)勢（除了在大型企業(yè)環(huán)境中）。 SOAP，不幸的是，它過時了，我們真的沒有看到太多的API把HTML作為結(jié)果返回給客戶端（除非你在構(gòu)建一個爬蟲程序）。

只要你返回給他們有效的數(shù)據(jù)格式，開發(fā)者就可以使用流行的語言和框架進行解析。如果你正在構(gòu)建一個通用的響應(yīng)對象并使用不同的序列化器，你也可以很容易的提供之前所提到的那些數(shù)據(jù)格式（不包括SOAP）。而你所要做的就是把使用方式放在響應(yīng)數(shù)據(jù)的接收頭里面。

一些API創(chuàng)建者建議向URL（端點之后）添加.json，.xml或.html文件擴展名以指定要返回的內(nèi)容類型，但我個人不喜歡這一點。我真的很喜歡Accept頭（它是內(nèi)置在HTTP規(guī)范），并且我覺得這么做也比較適當一些。

超媒體API

超媒體API很可能是RESTful API設(shè)計的未來。實際上是一個非常好的概念，它回歸到了HTTP和HTML如何運作的“本質(zhì)”。

當使用非超媒體RESTful API時，URL端點是服務(wù)器和使用者之間的約定的一部分。這些端點必須由客戶端提前知道，并且更改這些端點意味著客戶端不再能夠按預期與服務(wù)器通信。你可以先假定這是一個限制。

現(xiàn)在，API客戶端已經(jīng)不僅僅只有那些創(chuàng)建HTTP請求的用戶代理了。大多數(shù)HTTP請求是由人們通過瀏覽器產(chǎn)生的。人們不會被哪些預先定義好的RESTful API端點URL所約束。是什么讓人們變的如此與眾不同？人們可以閱讀內(nèi)容，點擊鏈接，看看有趣的標題，一般來說，探索一個網(wǎng)站，解釋內(nèi)容，去他們想去的地方。即使一個URL改變，人們也不受影響（除非，他們事先給某個頁面做了書簽，在這種情況下，他們?nèi)ブ黜摬l(fā)現(xiàn)原來有一條新的路徑可以去往之前的頁面）。

超媒體API概念的工作方式與人類相同。請求API的根返回一個URL列表，它可能指向每個信息集合，并以客戶端可以理解的方式描述每個集合。為每個資源提供ID并不重要（或必需），只要提供了一個URL即可。

隨著超媒體API的客戶端爬行鏈接和收集信息，URL在響應(yīng)中始終是***的，并且不需要事先知道作為約定的一部分。如果URL被緩存，并且后續(xù)請求返回404，則客戶端可以簡單地返回到根并再次發(fā)現(xiàn)內(nèi)容。

在檢索集合中的資源列表時，將返回包含各個資源的完整URL的屬性。當執(zhí)行POST / PATCH / PUT時，響應(yīng)可以是3xx重定向到完整的資源。

JSON不僅告訴了我們需要定義哪些屬性作為URL，也告訴了我們?nèi)绾螌RL與當前文檔關(guān)聯(lián)的語義。正如你猜的那樣，HTML就提供了這樣的信息。我們可能很樂意看到我們的API走完了完整的周期，并回到了處理HTML上來。想一下我們與CSS一起前行了多遠，有一天我們甚至可能會看到，API和網(wǎng)站使用完全相同的URL和內(nèi)容是常見的做法。

文檔

老實說，即便你不能***的遵循指南中的條款，你的API不一定是糟糕的。但是，如果你不為API準備文檔的話，沒有人會知道如何使用它，那它真的會成為一個糟糕的API。

使您的文檔可用于未經(jīng)身份驗證的開發(fā)人員。

不要使用自動文檔生成器，或者如果你這樣做，你也要保證自己審閱過并使其具有更好的版式。

不要截斷示例請求和響應(yīng)正文，要展示完整的東西。在文檔中使用語法高亮指示符。

記錄每個端點的預期響應(yīng)代碼和可能的錯誤消息，以及導致這些錯誤消息可能出現(xiàn)的錯誤。

如果您有空閑時間，請構(gòu)建一個開發(fā)人員API控制臺，以便開發(fā)人員可以立即試用您的API。這不像你想象的那么難，開發(fā)者（內(nèi)部和第三方）也會因此而擁戴你！

確保您的文檔可以打印; CSS是一個強大的東西;不要害怕在打印文檔時隱藏側(cè)邊欄。即使沒有人打印過物理副本，你會驚奇的發(fā)現(xiàn)有多少開發(fā)者喜歡打印到PDF以供離線閱讀。

勘誤：原始的HTTP封包

因為我們所做的一切都是通過HTTP，我將向你展示一個HTTP包的剖析。我經(jīng)常感到驚訝的是，有多少人不知道這些東西是什么樣子的！當客戶端向服務(wù)器發(fā)送請求時，它們提供一組鍵/值對，稱為標題，以及兩個換行符，***是請求體。這都是在同一個數(shù)據(jù)包中發(fā)送的。

服務(wù)器然后以所述鍵/值對格式，用兩個換行符然后響應(yīng)主體進行響應(yīng)。 HTTP是一個請求/響應(yīng)協(xié)議; 沒有“推送”支持（服務(wù)器向客戶端發(fā)送數(shù)據(jù)未經(jīng)安全），除非您使用不同的協(xié)議，如Websockets。

在設(shè)計API時，您應(yīng)該能夠使用允許查看原始HTTP數(shù)據(jù)包的工具。例如，考慮使用Wireshark。此外，請確保您使用的框架/ Web服務(wù)器，允許您閱讀和更改盡可能多的這些字段。

Example HTTP Request

POST /v1/animal HTTP/1.1
Host: api.example.org
Accept: application/json
Content-Type: application/json
Content-Length: 24

{   "name": "Gir",   "animal_type": 12 }

Example HTTP Response

HTTP/1.1 200 OK
Date: Wed, 18 Dec 2013 06:08:22 GMT
Content-Type: application/json
Access-Control-Max-Age: 1728000
Cache-Control: no-cache

{   "id": 12,   "created": 1386363036,   "modified": 1386363036,   "name": "Gir",   "animal_type": 12 }

責任編輯：張燕妮來源：知秋z