了解和使用 REST API

如果您考慮從 Internet 上的其他來源（例如 Twitter 或 Github）獲取數據，那麼您很可能會遇到“REST API”一詞。 但是什麼是 REST API？ 它能為你做什麼？ 你如何使用它？

在本文中，您將了解您需要了解的有關 REST API 的所有內容，以便能夠閱讀 API 文檔並有效地使用它們。

什麼是 REST API

假設您正在嘗試在 Youtube 上查找有關蝙蝠俠的視頻。 您打開 Youtube，在搜索字段中輸入“蝙蝠俠”，按 Enter，然後您會看到有關蝙蝠俠的視頻列表。 REST API 以類似的方式工作。 您搜索某些內容，然後從您請求的服務中獲得結果列表。

API是應用程序編程接口。 它是一組允許程序相互通信的規則。 開發人員在服務器上創建 API 並允許客戶端與之對話。

REST確定 API 的外觀。 它代表“代表性狀態轉移”。 它是開發人員在創建 API 時遵循的一組規則。 其中一條規則規定，當您鏈接到特定 URL 時，您應該能夠獲取一段數據（稱為資源）。

每個 URL 稱為請求，而發回給您的數據稱為響應。

請求剖析

重要的是要知道請求由四件事組成：

1. 端點
2. 方法
3. 標頭
4. 數據（或正文）

端點（或路由）是您請求的 url。 它遵循以下結構：

 root-endpoint/ ? root-endpoint/ ? root-endpoint/ ?

根端點是您請求的 API 的起點。 Github API 的根端點是https://api.github.com而 Twitter 的根端點是https://api.twitter.com 。

路徑決定了您請求的資源。 把它想像成一個自動應答機，它要求您按 1 獲得一項服務，按 2 獲得另一項服務，按 3 獲得另一項服務，依此類推。

您可以訪問路徑，就像您可以鏈接到網站的某些部分一樣。 例如，要獲取 Smashing Magazine 上標記為“JavaScript”的所有帖子的列表，請導航到https://www.smashingmagazine.com/tag/javascript/ 。 https://www.smashingmagazine.com/是根端點， /tag/javascript是路徑。

要了解您可以使用哪些路徑，您需要查看 API 文檔。 例如，假設您想通過 Github 的 API 獲取某個用戶的存儲庫列表。 文檔告訴您使用以下路徑來執行此操作：

 /users/:username/repos

路徑上的任何冒號 ( : ) 都表示一個變量。 您應該將這些值替換為發送請求時的實際值。 在這種情況下，您應該將:username替換為您正在搜索的用戶的實際用戶名。 如果我正在搜索我的 Github 帳戶，我會將:username替換為zellwk 。

在 Github 上獲取我的存儲庫列表的端點是：

 https://api.github.com/users/zellwk/repos

端點的最後一部分是查詢參數。 從技術上講，查詢參數不是 REST 架構的一部分，但您會看到很多 API 都在使用它們。 因此，為了幫助您完全理解如何閱讀和使用 API，我們還將討論它們。 查詢參數使您可以選擇使用鍵值對修改您的請求。 它們總是以問號 ( ? ) 開頭。 然後每個參數對用&號分隔，如下所示：

 ?query1=value1&query2=value2

當您嘗試在 Github 上獲取用戶存儲庫的列表時，您可以在請求中添加三個可能的參數來修改給您的結果：

如果您想獲得我最近推送到的存儲庫的列表，您可以將sort設置為push 。

 https://api.github.com/users/zellwk/repos?sort=pushed

你怎麼知道這個端點是否有效？ 好吧，是時候試一試了！

使用 curl 測試端點

您可以使用任何編程語言發送請求。 JavaScript 用戶可以使用 Fetch API 和 jQuery 的 Ajax 方法等方法； Ruby 用戶可以使用 Ruby 的 Net::HTTP 類，Python 用戶可以使用 Python Requests； 等等。

在本文中，我們將使用名為 cURL 的命令行實用程序。 我們使用 cURL 是因為 API 文檔通常是參考 cURL 編寫的。 如果您了解如何使用 cURL，那麼您在理解 API 文檔方面將毫無問題。 然後，您可以使用首選語言輕鬆執行請求。

在繼續之前，您需要確保您的計算機上安裝了 cURL。 打開終端並輸入curl -version 。 此命令檢查您在系統上安裝的 cURL 版本。

 curl --version

如果您沒有安裝 cURL，您將收到“找不到命令”錯誤。 如果您收到此錯誤，則需要在繼續之前安裝 curl。

要使用 cURL，請輸入curl ，然後輸入您請求的端點。 例如，要獲取 Github 的根端點，請鍵入以下內容：

 curl https://api.github.com

一旦你按下回車鍵，你應該會從 Github 收到如下所示的響應：

要獲取用戶存儲庫的列表，請將端點修改為正確的路徑，就像我們上面討論的那樣。 要獲取我的存儲庫列表，您可以使用以下命令：

 curl https://api.github.com/users/zellwk/repos

如果您希望在 cURL 中包含查詢參數，請確保在?之前添加反斜杠 ( \ ) 和=字符。 這是因為? 和=是命令行中的特殊字符。 您需要在命令行之前使用\將它們解釋為普通字符：

 curl https://api.github.com/users/zellwk/repos\?sort\=pushed

嘗試使用任一命令並執行請求！ 你會得到與你在 Github 的 root-endpont 中看到的類似的響應（但有更多的數據）。

JSON

JSON（JavaScript 對象表示法）一種用於通過 REST API 發送和請求數據的通用格式。 Github 發回給您的響應也採用 JSON 格式。

JSON 對像看起來像 JavaScript 對象。 在 JSON 中，每個屬性和值都必須用雙引號括起來，如下所示：

 { "property1": "value1", "property2": "value2", "property3": "value3" }

回到請求的剖析

您已經了解到請求由四個部分組成。

1. 端點
2. 方法
3. 標頭
4. 數據（或正文）

讓我們看看構成請求的其餘部分。

方法

該方法是您發送到服務器的請求類型。 您可以從以下五種類型中進行選擇：

• GET
• POST
• PUT
• PATCH
• DELETE

這些方法為您提出的請求提供了意義。 它們用於執行四種可能的操作： Create 、 Read 、 Update和Delete (CRUD)。

API 讓您知道使用每個請求的請求方法。 例如，要獲取用戶存儲庫的列表，您需要一個GET請求：

需要 GET 請求才能從用戶那裡獲取存儲庫列表。 要創建一個新的 Github 存儲庫，您需要一個POST請求：

您可以通過編寫-X或--request來設置 cURL 中的請求方法，然後是請求方法。 下面的這個命令嘗試通過 cURL 創建一個存儲庫：

 curl -X POST https://api.github.com/user/repos

嘗試運行此請求。 您將收到一條響應，告訴您需要進行身份驗證。 （稍後將詳細介紹身份驗證）。

 { "message": "Requires authentication", "documentation_url": "https://developer.github.com/v3" }

標題

標頭用於向客戶端和服務器提供信息。 它可用於多種用途，例如身份驗證和提供有關正文內容的信息。 您可以在 MDN 的 HTTP 標頭參考中找到有效標頭列表。

HTTP 標頭是由冒號分隔的屬性值對。 下面的示例顯示了一個標頭，它告訴服務器期望 JSON 內容。

 "Content-Type: application/json". Missing the opening ".

您可以通過-H或--header選項使用 curl 發送 HTTP 標頭。 要將上述標頭髮送到 Github 的 API，請使用以下命令：

 curl -H "Content-Type: application/json" https://api.github.com

（注意：Content-Type 標頭不是 Github 的 API 工作的必要條件。這只是一個示例，用於說明如何將標頭與 cURL 一起使用）。

要查看您發送的標頭，您可以在發送請求時使用-v或--verbose選項，如下所示：

 curl -H "Content-Type: application/json" https://api.github.com -v 

這裡， *是指 cURL 提供的附加信息。 >指的是請求頭， <指的是響應頭。

數據（或“正文”）

數據（有時稱為“正文”或“消息”）包含您希望發送到服務器的信息。 此選項僅用於POST 、 PUT 、 PATCH或DELETE請求。

要通過 cURL 發送數據，可以使用-d或--data選項：

 curl -X POST <URL> -d property1=value1

要發送多個數據字段，您可以創建多個-d選項：

 curl -X POST <URL> -d property1=value1 -d property2=value2

如果有意義，您可以將請求分成多行\以使其更易於閱讀：

 curl -X POST <URL> \ -d property1=value1 \ -d property2=value2

如果您知道如何啟動服務器，則可以創建 API 並測試您自己的數據。 如果你不知道，但有足夠的勇氣去嘗試，你可以按照這篇文章學習使用Node、Express和MongoDB創建服務器

如果您不想啟動服務器，可以訪問 Requestbin.com（它是免費的！ ）並單擊“創建端點”。 您將獲得一個可用於測試請求的 URL，如下圖所示的https://requestb.in/1ix963n1 。

如果您想測試您的請求，請確保創建自己的請求箱。 請求箱僅在創建後 48 小時內保持打開狀態。 當您閱讀本文時，我在上面創建的 bin 早已不復存在。

現在，嘗試將一些數據發送到您的請求箱，然後刷新您的箱的網頁。 您會看到一些數據，如下所示：

 curl -X POST https://requestb.in/1ix963n1 \ -d property1=value1 \ -d property2=value2 

默認情況下，cURL 發送數據就好像它們是通過頁面上的“表單域”發送的一樣。 如果您希望發送 JSON 數據，您需要將Content-Type設置為application/json ，並且您需要將數據格式化為 JSON 對象，如下所示：

 curl -X POST https://requestb.in/1ix963n1 \ -H "Content-Type: application/json" \ -d '{ "property1":"value1", "property2":"value2" }' 

這就是（幾乎！）您需要了解的有關請求結構的所有信息。

現在，還記得當您嘗試通過 Github 的 API 發送POST請求時，您收到一條消息“需要身份驗證”嗎？ 好吧，那是因為您無權執行POST請求！

驗證

未經您的許可，您不會允許任何人訪問您的銀行帳戶，對嗎？ 同樣的思路，開發人員採取措施確保您僅在您獲得授權時執行操作。 這可以防止其他人冒充您。

由於POST 、 PUT 、 PATCH和DELETE請求會更改數據庫，因此開發人員幾乎總是將它們放在身份驗證牆後面。 在某些情況下， GET請求還需要身份驗證（例如，當您訪問您的銀行帳戶以檢查當前餘額時）。

在網絡上，有兩種主要的方式來驗證自己：

1. 使用用戶名和密碼（也稱為基本身份驗證）
2. 使用秘密令牌

秘密令牌方法包括 oAuth，它允許您使用 Github、Google、Twitter、Facebook 等社交媒體網絡對自己進行身份驗證。

在本文中，您將只學習使用帶有用戶名和密碼的基本身份驗證。 如果您對使用 oAuth 進行身份驗證感興趣，我建議您閱讀 Zack Grossbart 的“您需要了解的關於 OAuth2 和使用 Facebook 登錄的知識”。

要使用 cURL 執行基本身份驗證，您可以使用-u選項，後跟您的用戶名和密碼，如下所示：

 curl -x POST -u "username:password" https://api.github.com/user/repos

嘗試在上述請求中使用您的用戶名和密碼進行身份驗證。 成功通過身份驗證後，您將看到響應從“需要身份驗證”更改為“解析 JSON 的問題”。

這是因為您尚未向服務器提供任何數據（所有POST 、 PUT 、 PATCH和DELETE請求都需要）。

有了到目前為止所學的知識，您應該能夠編輯上面的代碼，通過您的 cURL 創建一個 Github 存儲庫。 我會讓你自己試試！

現在，讓我們談談 HTTP 狀態代碼和錯誤消息。

HTTP 狀態代碼和錯誤消息

您之前收到的一些消息，例如“需要身份驗證”和“解析 JSON 的問題”是錯誤消息。 它們僅在您的請求出現問題時出現。 HTTP 狀態碼可讓您快速了解響應的狀態。 範圍從 100+ 到 500+。 一般來說，數字遵循以下規則：

1. 200+表示請求成功。
2. 300+表示請求被重定向到另一個 URL
3. 400+表示發生了源自客戶端的錯誤
4. 500+表示發生了源自服務器的錯誤

您可以使用詳細選項（ -v或--verbose ）或頭部選項（ -I或--head ）調試響應的狀態。

例如，如果您嘗試在POST請求中添加-I而不提供您的用戶名和密碼，您將獲得 401 狀態代碼（未授權）：

如果您的請求因數據錯誤或丟失而無效，您通常會收到 400 狀態代碼（錯誤請求）。

要獲取有關特定 HTTP 狀態代碼的更多信息，您可能需要查閱 MDN 的 HTTP 狀態參考。

API 版本

開發人員會不時更新他們的 API。 有時，API 可能會發生如此大的變化，以至於開發人員決定將他們的 API 升級到另一個版本。 如果發生這種情況，並且您的應用程序中斷，通常是因為您為舊 API 編寫了代碼，但您的請求指向了新 API。

您可以通過兩種方式請求特定的 API 版本。 您選擇哪種方式取決於 API 的編寫方式。

這兩種方式是：

1. 直接在端點
2. 在請求標頭中

例如，Twitter 使用第一種方法。 在撰寫本文時，Twitter 的 API 是 1.1 版，這通過它的端點很明顯：

 https://api.twitter.com/1.1/account/settings.json

另一方面，Github 使用第二種方法。 在撰寫本文時，Github 的 API 是第 3 版，您可以使用Accept標頭指定版本：

 curl https://api.github.com -H Accept:application/vnd.github.v3+json

包起來

在本文中，您了解了 REST API 是什麼以及如何使用 cURL 通過GET 、 POST 、 PUT 、 PATCH和DELETE方法執行請求。 此外，您還學習瞭如何使用-u選項對請求進行身份驗證，以及 HTTP 狀態的含義。

我希望這篇文章能夠幫助您充分了解 REST API，並且您可以在創建應用程序時流暢地使用它們。 如果您有任何問題，請隨時訪問我的博客或在下面留下您的評論。