如何更好的設計 RESTful API

當您的資料模型已開始穩定，您可以為您的網路應用程式建立公共API。 你意識到，很難對你的API進行重大更改，一旦它釋出，並希望儘可能得到儘可能多的前面。 現在，網際網路對API設計的意見有很多。 但是，因為沒有一個廣泛採用的標準在所有情況下都有效，所以你前面有一堆選擇：你應該接受什麼格式？ 你應該如何認證？ 你的API是否應該版本化？構建API是您可以做的最重要的事情之一，以提高您的服務的價值。 通過使用API，您的服務/核心應用程式有可能成為其他服務增長的平臺。 看看當前巨大的科技公司：Facebook，Twitter，谷歌，GitHub，亞馬遜，Netflix …沒有一個人會像今天一樣大，如果他們沒有通過API開啟他們的資料。 事實上，整個行業存在的唯一目的是消費由所述平臺提供的資料。

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

許多在網路上發現的API設計觀點是圍繞主觀的模糊標準解釋的學術討論，而不是在現實世界中有意義的。 我的目標是描述一個為當今的Web應用程式設計的務實的API的最佳實踐。 我沒有嘗試滿足一個標準，如果它不覺得正確。 為了幫助指導決策過程，我寫了一些API必須努力達到的要求：

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

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

RESTful API設計定義

以下是我將在本文件中使用的一些重要術語：

• Resource ：物件的單個例項。 例如，一隻動物。
• 集合：物件的集合。 例如，動物。
• HTTP ：用於通過網路通訊的協議。
• Consumer ：能夠發出HTTP請求的客戶端計算機應用程式。
• 第三方開發人員：不是您專案的一部分，但希望使用您的資料服務的開發人員。
• 伺服器：可通過網路從客戶端訪問的HTTP伺服器/應用程式。
• 端點：伺服器上的API網址，表示資源或整個集合。
• 冪等：無邊際效應，多次操作得到相同的結果。
• 網址區段：網址中的斜線分隔的資訊。

資料設計和抽象

首先將從你寫的開發文件API開始(比如我們可以看到各個開發平臺的暴露出來的API文件)，您需要決定如何設計資料，以及您的核心服務/應用程式如何工作。 如果你在做的API是第一次開發，這應該很容易。 如果您要將API附加到現有專案，則可能需要提供更多抽象(畢竟是要按照已有的文件規範來做)。

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

還有你的服務的很多部分，你不應該通過API公開。 一個常見的例子是許多API不允許第三方建立使用者。

設計資源請求

當然你知道GET和POST請求。當您的瀏覽器訪問不同的網頁時，這兩個最常用的請求。POST是如此受歡迎，它甚至流行語我們的平常的說話中，即使那些不知道網際網路如何工作的人也知道他們可以“釋出”的東西在朋友的Facebook上。

有四個半非常重要的HTTP動詞，你需要知道。我說“一半”，因為PATCH動詞非常類似於PUT動詞，兩個通常由許多API開發人員組合。這裡是動詞，在他們旁邊是他們相關的資料庫呼叫（我假設大多數人讀這個知道更多關於寫入資料庫而不是設計一個API）。

• GET （SELECT）：從伺服器檢索特定資源，或資源列表。
• POST （CREATE）：在伺服器上建立一個新的資源。
• PUT （UPDATE）：更新伺服器上的資源，提供整個資源。
• PATCH （UPDATE）：更新伺服器上的資源，僅提供更改的屬性。
• DELETE （DELETE）：從伺服器刪除資源。

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

• HEAD - 檢索有關資源的後設資料，例如資料的雜湊或上次更新時間。
• OPTIONS - 檢索關於客戶端被允許對資源做什麼的資訊。

一個好的RESTful API將使用四個半HTTP動詞，允許第三方與其資料進行互動，並且不會將動作/動詞作為URL段。

通常，GET請求可以被快取（通常是！）在瀏覽器，例如將快取請求頭用於第二次使用者的POST請求。 HEAD請求基本上是一個沒有響應主體的GET，並且也可以被快取。

版本控制

無論你正在構建什麼，無論你事先做了多少規劃，你的核心應用程式總會改變，你的資料關係總會改變，屬性新增和從你的資源中刪除。這只是軟體開發的工作原理，尤其是如果你的專案還活著並被許多人使用（如果你正在構建一個API，情況可能就會如此）。

記住，API是伺服器和客戶端之間的已釋出約定。如果您更改了伺服器API，這些更改會破壞向後相容性，那麼你就打破了這個約定，客戶端又會要求你重新支援它(誰讓客戶端依然是之前的版本，呼叫的還是之前的API)。為了避免這樣的事情，並讓您的客戶端滿意，您需要偶爾引入新版本的API，同時仍允許訪問舊版本。

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

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

一個好的RESTful API設計將跟蹤URL中的版本。另一個最常見的解決方案是將版本號放在請求頭中，但在與許多不同的第三方開發人員合作之後，我可以告訴您，新增這些請求頭資訊並不像新增網址細分那麼容易。

分析

跟蹤客戶端使用的API的版本/端點。 這可以像每次請求時在資料庫中增加一個整數一樣簡單。 有很多原因跟蹤API Analytics是一個好主意，例如，最常用的API呼叫應該是高效的。

為了構建第三方開發者所喜歡的API，最重要的是，當您棄用某個版本的API時，實際上可以使用已棄用的API功能與開發人員聯絡(在兩個異構系統中當對方的開發人員呼叫本服務時順帶告知對方)。 這是提醒他們在棄用舊API版本之前升級的完美方法。

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

API Root URL

無論你相信與否，您的API的根位置是重要的。當開發人員使用您的API接手舊專案並需要構建新功能時，他們可能根本不知道您有哪些服務。幸好他們知道客戶端對外呼叫的那些URL列表。重要的是，進入您的API的根入口點儘可能簡單，因為長的複雜URL將顯得令人生畏，並可能使開發人員直接略過而不會採用。

這裡有兩個常見的URL根：

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

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

如果您預計您的API將不會增長到那麼大，或者您想要一個更簡單的應用程式設定（例如，您希望從同一個框架託管網站和API），將您的API放置在域根的URL段（例如 / api / ）也有效。

將內容設為您的API根目錄是個好主意。例如，點選GitHub的API的根會返回一個端點列表。就個人而言，我喜歡使用根網址提供給開發人員認為有用的資訊，例如，如何獲取API的開發人員文件。

此外，請注意HTTPS字首。作為一個好的RESTful API，您必須在HTTPS之後託管您的API(一個好的RESTful API總是基於HTTPS來發布的)。

端點

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

如果你正在構建一個虛擬的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動詞和端點組合。例如，這裡有一個半全面的行動列表，可以使用我們虛構的API執行。請注意，我在每個端點之前都有HTTP動詞，因為這是在HTTP請求標頭中使用的相同符號。

• GET / zoos：列出所有動物園（ID和名稱，不要太多細節）
• POST / zoos：建立一個新的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：建立一個新的動物
• 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：建立一個新員工
• POST / zoos / ZID / employees：在特定動物園僱用員工
• DELETE / zoos / ZID / employees / EID：從特定的動物園中解僱員工

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

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

注意資料之間的關係如何顯示，特別是僱員和動物園之間的多對多關係。通過新增其他網址細分，您可以執行更具體的互動。當然，對於“FIRE(解僱)”沒有HTTP動詞，但是通過對位於Zoo內的Employee執行DELETE，我們能夠實現相同的效果。

過濾器

當客戶端請求物件列表時，請務必為它們提供符合所請求條件的每個物件的列表。這個列表可能是巨大的。但是，重要的是不要對資料執行任何任意限制。正是這些任意的限制使第三方開發者很難知道發生了什麼。如果他們請求某個集合，並迭代結果，他們從來沒有看到超過100個結果，接下來他們就不得不去查詢這個限制條件的出處(提供服務端沒有問題，就只能是呼叫端的問題了)。到底是他們的ORM的bug導致的，還是因為網路截斷了大資料包？

儘可能減少那些會影響到第三方開發者開發的無謂限制

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

過濾主要用於對資源集合執行GET。由於這些是GET請求，因此應通過URL傳遞過濾資訊。以下是您可能想要新增到API的過濾型別的一些示例：

• ?limit = 10:減少返回給Consumer的結果數（用於分頁）
• ?offset = 10:向客戶端傳送資訊集（用於分頁）
• ?animal_type_id = 1:過濾符合以下條件的記錄（WHERE animal_type_id = 1）
• ?sortby = name&order = asc:根據指定的屬性對結果進行排序（ORDER BYname ASC）

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

還有一個要說的是，每當您執行資料的過濾或排序時，請確保您列出客戶端可以過濾和排序的列。我們不希望將任何資料庫錯誤傳送給客戶端！

狀態碼

作為RESTful API，使用正確的HTTP狀態程式碼非常重要;他們是一個標準！各種網路裝置能夠讀取這些狀態碼，例如，負載平衡器可以配置為避免向傳送大量50x錯誤的Web伺服器傳送請求。有很多HTTP狀態程式碼可供選擇，但此列表應該是一個很好的起點：

• 200 OK – [GET]
• 客戶端從伺服器請求資料，伺服器為它們找到它（等冪）
• 201 CREATED – [POST / PUT / PATCH]
• 客戶端提供了伺服器資料，並且伺服器建立了一個資源
• 204 無內容 – [刪除]
• 客戶端要求伺服器刪除資源，並且伺服器將其刪除
• 400 無效請求 – [POST / PUT / PATCH]
• 客戶端給伺服器的資料不良，伺服器沒有做任何事情（冪等）
• *錯誤404 – []

  *客戶端引用了一個不存在的資源或集合，並且伺服器什麼也不做（冪等）

• *500內部伺服器錯誤 – []

  *伺服器遇到錯誤，並且客戶端不知道請求是否成功

狀態碼範圍

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

2xx 範圍保留用於成功訊息，儘可能確保您的伺服器儘可能多地向客戶端傳送這些訊息。

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

4xx 範圍保留用於響應客戶端做出的錯誤，例如。他們提供不良資料或要求不存在的東西。這些請求應該是冪等的，而不是更改伺服器的狀態。

5xx 範圍的狀態碼是保留給伺服器端錯誤用的。這些錯誤常常是從底層的函式丟擲來的，甚至開發人員也通常沒法處理，傳送這類狀態碼的目的以確保客戶端獲得某種響應。當收到5xx響應時，客戶端不可能知道伺服器的狀態，所以這類狀態碼是要儘可能的避免。

預期的返回文件

當使用不同的HTTP動詞對伺服器端點執行操作時，客戶端需要在返回結果裡面拿到一系列的資訊。 下面的列表是非常典型的RESTful API：

• GET / collection：返回資源物件的列表（陣列）
• GET / collection / resource：返回單個Resource物件
• POST / collection：返回新建立的Resource物件
• PUT / collection / resource：返回完整的Resource物件
• PATCH / collection / resource：返回完整的Resource物件
• DELETE / collection / resource：返回一個空文件

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

###認證

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

OAuth 2.0提供了一個很好的方法。對於每個請求，您可以確定知道哪個客戶正在發出請求，代表他們請求哪個使用者，並提供一種（大部分）標準化的方式來過期訪問或允許使用者撤消來自客戶端的訪問權，需要第三方客戶端知道使用者登入憑據。

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

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

內容型別

目前，最令人興奮的API提供來自RESTful介面的JSON資料。這包括Facebook，Twitter，GitHub，你命名。 XML似乎已經失去了優勢（除了在大型企業環境中）。 SOAP，不幸的是，它過時了，我們真的沒有看到太多的API把HTML作為結果返回給客戶端（除非你在構建一個爬蟲程式）。

只要你返回給他們有效的資料格式，開發者就可以使用流行的語言和框架進行解析。如果你正在構建一個通用的響應物件並使用不同的序列化器，你也可以很容易的提供之前所提到的那些資料格式（不包括SOAP）。而你所要做的就是把使用方式放在響應資料的接收頭裡面。

一些API建立者建議向URL（端點之後）新增.json，.xml或.html副檔名以指定要返回的內容型別，但我個人不喜歡這一點。我真的很喜歡Accept頭（它是內建在HTTP規範），並且我覺得這麼做也比較適當一些。

超媒體API

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

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

現在，API客戶端已經不僅僅只有那些建立HTTP請求的使用者代理了。大多數HTTP請求是由人們通過瀏覽器產生的。人們不會被哪些預先定義好的RESTful API端點URL所約束。是什麼讓人們變的如此與眾不同？人們可以閱讀內容，點選連結，看看有趣的標題，一般來說，探索一個網站，解釋內容，去他們想去的地方。即使一個URL改變，人們也不受影響（除非，他們事先給某個頁面做了書籤，在這種情況下，他們去主頁並發現原來有一條新的路徑可以去往之前的頁面）。

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

隨著超媒體API的客戶端爬行連結和收集資訊，URL在響應中始終是最新的，並且不需要事先知道作為約定的一部分。如果URL被快取，並且後續請求返回404，則客戶端可以簡單地返回到根並再次發現內容。

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

JSON不僅告訴了我們需要定義哪些屬性作為URL，也告訴了我們如何將URL與當前文件關聯的語義。正如你猜的那樣，HTML就提供了這樣的資訊。我們可能很樂意看到我們的API走完了完整的週期，並回到了處理HTML上來。想一下我們與CSS一起前行了多遠，有一天我們甚至可能會看到，API和網站使用完全相同的URL和內容是常見的做法。

文件

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

使您的文件可用於未經身份驗證的開發人員。

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

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

記錄每個端點的預期響應程式碼和可能的錯誤訊息，以及導致這些錯誤訊息可能出現的錯誤。

如果您有空閒時間，請構建一個開發人員API控制檯，以便開發人員可以立即試用您的API。這不像你想象的那麼難，開發者（內部和第三方）也會因此而擁戴你！

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

勘誤：原始的HTTP封包

因為我們所做的一切都是通過HTTP，我將向你展示一個HTTP包的剖析。 我經常感到驚訝的是，有多少人不知道這些東西是什麼樣子的！ 當客戶端向伺服器傳送請求時，它們提供一組鍵/值對，稱為標題，以及兩個換行符，最後是請求體。 這都是在同一個資料包中傳送的。

伺服器然後以所述鍵/值對格式，用兩個換行符然後響應主體進行響應。 HTTP是一個請求/響應協議; 沒有“推送”支援（伺服器向客戶端傳送資料未經安全），除非您使用不同的協議，如Websockets。

在設計API時，您應該能夠使用允許檢視原始HTTP資料包的工具。 例如，考慮使用Wireshark。 此外，請確保您使用的框架/ Web伺服器，允許您閱讀和更改儘可能多的這些欄位。

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
}