了解和使用 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，并且您可以在创建应用程序时流畅地使用它们。 如果您有任何问题，请随时访问我的博客或在下面留下您的评论。