如果你想要獲取我最近推送過(guò)的存儲(chǔ)庫(kù)列表，你可以將排序方式設(shè)置為push。

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

你怎么知道這個(gè)端點(diǎn)是否有效呢？好吧，是時(shí)候試一試了！

使用curl測(cè)試端點(diǎn)

您可以使用任何編程語(yǔ)言發(fā)送請(qǐng)求。JavaScript 用戶可以使用 Fetch API 和 jQuery 的 Ajax 方法等方法；Ruby 用戶可以使用 Ruby 的 Net：：HTTP 類，Python 用戶可以使用 Python Requests;等等。

在本文中，我們將使用命令行工具cURL。我們使用cURL是因?yàn)锳PI文檔通常會(huì)參考cURL。如果您了解如何使用 cURL，那么理解 API 文檔就不會(huì)有問(wèn)題。然后，你可以輕松地用你喜歡的語(yǔ)言執(zhí)行請(qǐng)求。

在繼續(xù)之前，您需要確保計(jì)算機(jī)上已安裝 cURL。打開(kāi)您的終端，輸入curl –version 。此命令檢查您在系統(tǒng)上安裝的 cURL 版本。

curl --version

如果您沒(méi)有安裝 cURL，您將收到 “command not found” 錯(cuò)誤。如果您收到此錯(cuò)誤，則需要在繼續(xù)之前安裝 curl。

要使用 cURL，你輸入curl，然后鍵入要請(qǐng)求的終端節(jié)點(diǎn)。例如，要獲取 Github 的根終端節(jié)點(diǎn)，你輸入以下內(nèi)容：

curl https://api.github.com

按 Enter 鍵后，您應(yīng)該會(huì)收到來(lái)自 Github 的響應(yīng)，如下所示：

要獲取用戶存儲(chǔ)庫(kù)的列表，你需要將端點(diǎn)修改為正確的路徑，就像我們上面討論的那樣。要獲取我的存儲(chǔ)庫(kù)列表，您可以使用以下命令：

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

如果您希望在 cURL 中包含查詢參數(shù)，，請(qǐng)確保在?和=字符前加上反斜杠（\）。。這是因?yàn)?和=是命令行中的特殊字符。你需要在它們前面加上\，以便命令行將它們解釋為普通字符：

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

嘗試使用任一命令并執(zhí)行請(qǐng)求！你將獲得與Github根端點(diǎn)類似的響應(yīng)（但包含更多數(shù)據(jù)）。

JSON格式

JSON（JavaScript 對(duì)象表示法）：一種通過(guò) REST API 發(fā)送和請(qǐng)求數(shù)據(jù)的常用格式。Github發(fā)送給你的響應(yīng)也是以JSON格式編寫的。

JSON 對(duì)象看起來(lái)像 JavaScript 對(duì)象。在 JSON 中，每個(gè)屬性和值都必須用雙引號(hào)括起來(lái)，如下所示：

{

  "property1": "value1",

  "property2": "value2",

  "property3": "value3"

}

返回請(qǐng)求剖析

您已經(jīng)了解到請(qǐng)求由四個(gè)部分組成。

1. 終端節(jié)點(diǎn)
2. 方法
3. 標(biāo)頭
4. 數(shù)據(jù)（或正文）

讓我們繼續(xù)了解構(gòu)成請(qǐng)求的其他內(nèi)容。

方法

method 是您發(fā)送到服務(wù)器的請(qǐng)求類型。您可以從以下五種類型中進(jìn)行選擇：

• GET
• POST
• PUT
• PATCH
• DELETE

這些方法為你正在發(fā)出的請(qǐng)求提供意義。它們用于執(zhí)行四種可能的操作：創(chuàng)建、讀取、更新和刪除（CRUD）。

API 讓您知道使用每個(gè)請(qǐng)求的請(qǐng)求方法。例如，要獲取用戶倉(cāng)庫(kù)的列表，您需要一個(gè)GET 請(qǐng)求：

需要 GET 請(qǐng)求才能從用戶那里獲取存儲(chǔ)庫(kù)列表。要?jiǎng)?chuàng)建新的 Github 存儲(chǔ)庫(kù)，您需要一個(gè) POST 請(qǐng)求：

你可以通過(guò)在 cURL 中寫入 -X 或 –request，然后跟隨請(qǐng)求方法來(lái)設(shè)置請(qǐng)求方法。以下命令嘗試通過(guò) cURL 創(chuàng)建一個(gè)存儲(chǔ)庫(kù)：

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

嘗試運(yùn)行此請(qǐng)求。您將收到一個(gè)響應(yīng)，告訴您需要身份驗(yàn)證。（稍后將詳細(xì)介紹身份驗(yàn)證）。

{

  "message": "Requires authentication",

  "documentation_url": "https://developer.github.com/v3"

}

頭部信息

頭部信息用于向客戶端和服務(wù)器提供信息。它可用于多種用途，例如身份驗(yàn)證和提供有關(guān)正文內(nèi)容的信息。您可以在 MDN 的 HTTP Headers Reference 中找到有效標(biāo)頭的列表。

HTTP 頭部是屬性-值對(duì)，用冒號(hào)分隔。下面的示例顯示了一個(gè)告訴服務(wù)器期望 JSON 內(nèi)容的頭部。

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

你可以通過(guò)使用 -H 或 –header 選項(xiàng)在 cURL 中發(fā)送 HTTP 頭部信息。要將上述頭部信息發(fā)送到 GitHub 的 API，你可以使用以下命令：

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

（注意：Content-Type 頭部不是 GitHub API 工作的必要條件。這只是一個(gè)示例，用于說(shuō)明如何將標(biāo)頭與 cURL 一起使用）。

要查看已發(fā)送的頭部信息，你可以在發(fā)送請(qǐng)求時(shí)使用 -v 或 –verbose 選項(xiàng)，如下所示：

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

這里，* 指的是 cURL 提供的額外信息。> 指的是請(qǐng)求頭部，< 指的是響應(yīng)頭部。

數(shù)據(jù)（或“正文”）

數(shù)據(jù)（有時(shí)稱為 “body” 或 “message”） 包含要發(fā)送到服務(wù)器的信息。這個(gè)選項(xiàng)僅用于 POST、PUT、PATCH 或 DELETE 請(qǐng)求。

要通過(guò) cURL 發(fā)送數(shù)據(jù)，你可以使用 -d 或 –data 選項(xiàng)：

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

要發(fā)送多個(gè)數(shù)據(jù)字段，你可以創(chuàng)建多個(gè) -d 選項(xiàng)：

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

如果合適，你可以將請(qǐng)求拆分成多行 \ 以使其更易讀：

curl -X POST <URL> \

  -d property1=value1 \

  -d property2=value2

如果您知道如何啟動(dòng)服務(wù)器，你可以創(chuàng)建一個(gè) API 并測(cè)試你自己的數(shù)據(jù)。如果您不知道，但有足夠的勇氣嘗試，您可以按照本文學(xué)習(xí)使用 Node、Express 和 MongoDB 創(chuàng)建服務(wù)器。

如果您不想啟動(dòng)您的服務(wù)器，您可以轉(zhuǎn)到 Requestbin.com（它是免費(fèi)的！）并單擊 “create endpoint”。您將獲得一個(gè)可用于測(cè)試請(qǐng)求的 URL，如下圖所示。https://requestb.in/1ix963n1

如果要測(cè)試您的請(qǐng)求，請(qǐng)確保創(chuàng)建自己的請(qǐng)求箱。請(qǐng)求 bin 僅在創(chuàng)建后保持打開(kāi) 48 小時(shí)。當(dāng)您閱讀本文時(shí)，我在上面創(chuàng)建的 bin 早已不見(jiàn)了。

現(xiàn)在，嘗試將一些數(shù)據(jù)發(fā)送到您的請(qǐng)求 Bin，然后刷新 Bin 的網(wǎng)頁(yè)。您將看到一些數(shù)據(jù)，如下所示：

curl -X POST https://requestb.in/1ix963n1 \

  -d property1=value1 \

  -d property2=value2

默認(rèn)情況下，cURL 發(fā)送數(shù)據(jù)，就像通過(guò)頁(yè)面上的“表單字段”發(fā)送數(shù)據(jù)一樣。如果要發(fā)送 JSON 數(shù)據(jù)，你需要將 Content-Type 設(shè)置為 application/json，并且需要將你的數(shù)據(jù)格式化為 JSON 對(duì)象，如下所示：

curl -X POST https://requestb.in/1ix963n1 \

  -H "Content-Type: application/json" \

  -d '{

  "property1":"value1",

  "property2":"value2"

}'

這就是您需要了解的有關(guān)請(qǐng)求結(jié)構(gòu)的所有信息。

現(xiàn)在，還記得當(dāng)你嘗試通過(guò) GitHub 的 API 發(fā)送一個(gè) POST 請(qǐng)求時(shí)，你得到了一條消息說(shuō)“Requires authentication”嗎？這是因?yàn)槟銢](méi)有權(quán)限執(zhí)行這個(gè) POST 請(qǐng)求！

認(rèn)證

你不會(huì)允許任何人未經(jīng)你的許可訪問(wèn)你的銀行賬戶，對(duì)嗎？同樣的道理，開(kāi)發(fā)人員會(huì)采取措施，確保您只有在授權(quán)的情況下才能執(zhí)行操作。這可以防止其他人冒充您。

由于 POST、PUT、PATCH 和 DELETE 請(qǐng)求會(huì)修改數(shù)據(jù)庫(kù)，開(kāi)發(fā)人員幾乎總是將它們放在認(rèn)證墻后面。在某些情況下，GET 請(qǐng)求也需要認(rèn)證（例如，當(dāng)你訪問(wèn)你的銀行賬戶以檢查當(dāng)前余額時(shí)）。

在 Web 上，有兩種主要方法可以驗(yàn)證自己的身份：

1. 使用用戶名和密碼（也稱為基本身份驗(yàn)證）
2. 使用 secret 令牌

秘密令牌方法包括 oAuth，它允許您使用 Github、Google、Twitter、Facebook 等社交媒體網(wǎng)絡(luò)對(duì)自己進(jìn)行身份驗(yàn)證。

在本文中，您將只學(xué)習(xí)如何使用用戶名和密碼的基本身份驗(yàn)證。如果您對(duì)使用 oAuth 進(jìn)行身份驗(yàn)證感興趣，我建議您閱讀 Zack Grossbart 撰寫的“您需要了解的有關(guān) OAuth2 和使用 Facebook 登錄的信息”。

要使用 cURL 進(jìn)行基本認(rèn)證，你可以使用 -u 選項(xiàng)，后面跟著你的用戶名和密碼，如下所示：

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

嘗試在上述請(qǐng)求中使用您的用戶名和密碼進(jìn)行身份驗(yàn)證。身份驗(yàn)證成功后，您將看到響應(yīng)從“需要身份驗(yàn)證”更改為“解析 JSON 時(shí)出現(xiàn)問(wèn)題”。

這是因?yàn)槟氵€沒(méi)有提供任何數(shù)據(jù)（所有 POST、PUT、PATCH 和 DELETE 請(qǐng)求都需要數(shù)據(jù)）給服務(wù)器。

憑借您目前所學(xué)的知識(shí)，您應(yīng)該能夠編輯上面的代碼，以通過(guò) cURL 創(chuàng)建 Github 存儲(chǔ)庫(kù)。我會(huì)留給你自己嘗試！

現(xiàn)在，我們來(lái)談?wù)?HTTP 狀態(tài)代碼和錯(cuò)誤消息。

HTTP狀態(tài)代碼和錯(cuò)誤消息

您之前收到的一些消息（如“需要身份驗(yàn)證”和“解析 JSON 時(shí)出錯(cuò)”）是錯(cuò)誤消息。它們僅在您的請(qǐng)求有問(wèn)題時(shí)出現(xiàn)。 HTTP 狀態(tài)碼讓你快速了解響應(yīng)的狀態(tài)。范圍從 100+ 到 500+。通常，這些數(shù)字遵循以下規(guī)則：

1. 200+ 表示請(qǐng)求已成功。
2. 300+ 表示請(qǐng)求被重定向到另一個(gè) URL
3. 400+ 表示發(fā)生了源自客戶端的錯(cuò)誤
4. 500+ 表示發(fā)生了源自服務(wù)器的錯(cuò)誤

你可以使用詳細(xì)選項(xiàng)（-v 或 –verbose）或頭部選項(xiàng)（-I 或 –head）調(diào)試響應(yīng)的狀態(tài)。

例如，如果你嘗試在沒(méi)有提供用戶名和密碼的情況下向 POST 請(qǐng)求添加 -I，你會(huì)得到一個(gè)401狀態(tài)碼（未授權(quán)）：

如果你的請(qǐng)求無(wú)效是因?yàn)槟愕臄?shù)據(jù)錯(cuò)誤或缺失，你通常會(huì)得到一個(gè)400狀態(tài)碼（錯(cuò)誤請(qǐng)求）。

要獲取有關(guān)特定 HTTP 狀態(tài)碼的更多信息，你可能需要查閱 MDN 的 HTTP 狀態(tài)參考。

API版本

開(kāi)發(fā)人員會(huì)不時(shí)更新他們的 API。有時(shí)，API 可能會(huì)發(fā)生很大變化，以至于開(kāi)發(fā)人員決定將其 API 升級(jí)到另一個(gè)版本。如果發(fā)生這種情況，并且你的應(yīng)用程序出現(xiàn)故障，通常是因?yàn)槟呀?jīng)為較舊的 API 編寫了代碼，但您的請(qǐng)求指向了較新的 API。

您可以通過(guò)兩種方式請(qǐng)求特定的 API 版本。選擇哪種方式取決于 API 的編寫方式。

這兩種方式是：

1. 直接在終端節(jié)點(diǎn)中
2. 在請(qǐng)求標(biāo)頭中

例如，Twitter 使用第一種方法。在撰寫本文時(shí)，Twitter 的 API 版本為 1.1，這可以通過(guò)其端點(diǎn)明顯看出：

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

另一方面，GitHub 使用第二種方法。截至撰寫本文時(shí)，GitHub 的 API 版本是 3，你可以通過(guò)一個(gè) Accept 頭來(lái)指定版本：

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

總結(jié)

在本文中，您了解了什么是 REST API 以及如何使用 cURL 進(jìn)行 GET、POST、PUT、PATCH 和 DELETE 方法的請(qǐng)求。此外，你還學(xué)會(huì)了如何通過(guò) -u 選項(xiàng)對(duì)請(qǐng)求進(jìn)行身份驗(yàn)證，以及 HTTP 狀態(tài)碼的含義。

我希望本文能幫助您充分了解 REST API，并且您可以在創(chuàng)建應(yīng)用程序時(shí)流暢地使用它們。

原文鏈接：https://www.smashingmagazine.com/2018/01/understanding-using-rest-api/

#你可能也喜歡這些API文章!

掌握ChatGPT插件與自定義GPT

REST APIs與微服務(wù)：關(guān)鍵差異

2024年最佳天氣API

能打敗谷歌的5個(gè)最有用的SERP API

使用Pixabay API從關(guān)鍵字免費(fèi)獲取圖片和視頻

如何使用免費(fèi)工具進(jìn)行接口返回?cái)?shù)據(jù)的加密與解密

免費(fèi)YAML格式校驗(yàn)API的使用指南與集成教程

如何免費(fèi)調(diào)用微博熱搜API獲取最新熱門話題

小紅書(shū)違禁詞替換API的免費(fèi)版與付費(fèi)版對(duì)比