了解和使用REST API

关于REST API，你需要从头到尾了解的一切。如何使用REST API以及为什么要使用它们，如何处理头部信息、错误信息和API版本。在本文中，Zell Liew将向你展示关于REST API的所有必备知识，以便能够阅读 API 文档并有效地使用它们。此外，您还将学习如何使用 -u 选项对请求进行身份验证，以及 HTTP 状态的含义。让我们开始吧！

如果你想过从互联网上的其他来源（如Twitter或Github）获取数据，那么你很可能遇到过“REST API”这个术语。但是，REST API是什么？它能为你做什么？你该如何使用它？

在本文中，你将学习关于REST API的所有必备知识，以便能够阅读 API 文档并有效地使用它们。

什么是REST API

假设您正在尝试在 Youtube 上查找有关蝙蝠侠的视频。你打开 Youtube，在搜索字段中输入 “蝙蝠侠”，按下回车键，你会看到一个关于蝙蝠侠的视频列表。REST API 的工作方式与此类似。您搜索某些内容，并从您请求的服务中获得返回的结果列表。

API 是一种应用程序编程接口。它是一组允许程序相互通信的规则。开发人员在服务器上创建 API 并允许客户端与其通信。

REST 确定 API 的外观。它代表“表述性状态转移”（Representational State Transfer）。这是开发人员在创建 API 时遵循的一组规则。其中一条规则规定，当您链接到特定 URL 时，您应该能够获取一段数据（称为资源）。

每个 URL 称为一个请求，而发送给你的数据被称为响应。

请求的剖析

了解请求的四个组成部分非常重要：

端点（endpoint）
方法（method）
头部（headers）
数据（或正文）（data or body）

终端节点（或路由）是您请求的 URL。它遵循以下结构：

root-endpoint/?

根端点（root-endpoint）是你正在请求的API的起点。Github API的根端点是https://api.github.com，而Twitter API的根端点是https://api.twitter.com。

路径（path）决定了你正在请求的资源。你可以把它想象成一个自动应答机，要求您按 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 上获取用户的存储库列表时，您需要在请求中添加三个可能的参数来修改提供给您的结果：

如果你想要获取我最近推送过的存储库列表，你可以将排序方式设置为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，您将收到 “command not found” 错误。如果您收到此错误，则需要在继续之前安装 curl。

要使用 cURL，你输入curl，然后键入要请求的终端节点。例如，要获取 Github 的根终端节点，你输入以下内容：

curl https://api.github.com

按 Enter 键后，您应该会收到来自 Github 的响应，如下所示：

要获取用户存储库的列表，你需要将端点修改为正确的路径，就像我们上面讨论的那样。要获取我的存储库列表，您可以使用以下命令：

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

如果您希望在 cURL 中包含查询参数，，请确保在?和=字符前加上反斜杠（\）。。这是因为?和=是命令行中的特殊字符。你需要在它们前面加上\，以便命令行将它们解释为普通字符：

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

尝试使用任一命令并执行请求！你将获得与Github根端点类似的响应（但包含更多数据）。

JSON格式

JSON（JavaScript 对象表示法）：一种通过 REST API 发送和请求数据的常用格式。Github发送给你的响应也是以JSON格式编写的。

JSON 对象看起来像 JavaScript 对象。在 JSON 中，每个属性和值都必须用双引号括起来，如下所示：

{

  "property1": "value1",

  "property2": "value2",

  "property3": "value3"

}

返回请求剖析

您已经了解到请求由四个部分组成。

终端节点
方法
标头
数据（或正文）

让我们继续了解构成请求的其他内容。

方法

method 是您发送到服务器的请求类型。您可以从以下五种类型中进行选择：

GET
POST
PUT
PATCH
DELETE

这些方法为你正在发出的请求提供意义。它们用于执行四种可能的操作：创建、读取、更新和删除（CRUD）。

”GET’	此请求用于从服务器获取资源。如果您执行 ‘GET’ 请求，服务器会查找您请求的数据并将其发送回给您。换句话说，“GET”请求执行“READ”操作。这是默认的请求方法。
‘POST’	此请求用于在服务器上创建新资源。如果您执行 ‘POST’ 请求，服务器会在数据库中创建一个新条目，并告诉您创建是否成功。换句话说，“POST”请求执行“CREATE”操作。
‘PUT’ 和 ‘PATCH’	这两个请求用于更新服务器上的资源。如果您执行 ‘PUT’ 或 ‘PATCH’ 请求，服务器会更新数据库中的条目并告诉您更新是否成功。换句话说，“PUT”或“PATCH”请求执行“UPDATE”操作。
‘删除’	此请求用于从服务器中删除资源。如果您执行 ‘DELETE’ 请求，服务器将删除数据库中的条目并告诉您删除是否成功。换句话说，“DELETE”请求执行“DELETE”操作。

API 让您知道使用每个请求的请求方法。例如，要获取用户仓库的列表，您需要一个GET 请求：

需要 GET 请求才能从用户那里获取存储库列表。要创建新的 Github 存储库，您需要一个 POST 请求：

需要 POST 请求来创建一个新的存储库

你可以通过在 cURL 中写入 -X 或 –request，然后跟随请求方法来设置请求方法。以下命令尝试通过 cURL 创建一个存储库：

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

尝试运行此请求。您将收到一个响应，告诉您需要身份验证。（稍后将详细介绍身份验证）。

{

  "message": "Requires authentication",

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

}

头部信息

头部信息用于向客户端和服务器提供信息。它可用于多种用途，例如身份验证和提供有关正文内容的信息。您可以在 MDN 的 HTTP Headers Reference 中找到有效标头的列表。

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 提供的额外信息。> 指的是请求头部，< 指的是响应头部。

数据（或“正文”）

数据（有时称为 “body” 或 “message”）包含要发送到服务器的信息。这个选项仅用于 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（它是免费的！）并单击 “create endpoint”。您将获得一个可用于测试请求的 URL，如下图所示。https://requestb.in/1ix963n1

如果要测试您的请求，请确保创建自己的请求箱。请求 bin 仅在创建后保持打开 48 小时。当您阅读本文时，我在上面创建的 bin 早已不见了。

现在，尝试将一些数据发送到您的请求 Bin，然后刷新 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 请求时，你得到了一条消息说“Requires authentication”吗？这是因为你没有权限执行这个 POST 请求！

认证

你不会允许任何人未经你的许可访问你的银行账户，对吗？同样的道理，开发人员会采取措施，确保您只有在授权的情况下才能执行操作。这可以防止其他人冒充您。

由于 POST、PUT、PATCH 和 DELETE 请求会修改数据库，开发人员几乎总是将它们放在认证墙后面。在某些情况下，GET 请求也需要认证（例如，当你访问你的银行账户以检查当前余额时）。

在 Web 上，有两种主要方法可以验证自己的身份：

使用用户名和密码（也称为基本身份验证）
使用 secret 令牌

秘密令牌方法包括 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+。通常，这些数字遵循以下规则：

200+ 表示请求已成功。
300+ 表示请求被重定向到另一个 URL
400+ 表示发生了源自客户端的错误
500+ 表示发生了源自服务器的错误

你可以使用详细选项（-v 或 –verbose）或头部选项（-I 或 –head）调试响应的状态。

例如，如果你尝试在没有提供用户名和密码的情况下向 POST 请求添加 -I，你会得到一个401状态码（未授权）：

如果你的请求无效是因为你的数据错误或缺失，你通常会得到一个400状态码（错误请求）。

要获取有关特定 HTTP 状态码的更多信息，你可能需要查阅 MDN 的 HTTP 状态参考。

API版本

开发人员会不时更新他们的 API。有时，API 可能会发生很大变化，以至于开发人员决定将其 API 升级到另一个版本。如果发生这种情况，并且你的应用程序出现故障，通常是因为您已经为较旧的 API 编写了代码，但您的请求指向了较新的 API。

您可以通过两种方式请求特定的 API 版本。选择哪种方式取决于 API 的编写方式。

这两种方式是：

直接在终端节点中
在请求标头中

例如，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，并且您可以在创建应用程序时流畅地使用它们。

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