使用 RESTful API 探索艺术世界

在数字化时代，API作为连接不同系统和服务的桥梁，对于构建应用程序和集成服务至关重要。本文将引导读者如何构建和使用API，特别是通过Python和JavaScript进行身份验证，并利用博物馆API发现艺术品。

文章首先介绍构建本地API的基础，包括技术实现和设计最佳实践，为服务间通信打下基础。随后，深入探讨身份验证策略，使用Python和JavaScript确保API安全访问，保护数据安全。

掌握API构建和保护后，文章转向查询博物馆API，展示如何获取艺术品信息，体现API在文化领域的应用。同时，讲解如何处理API响应，解析数据，对构建成功应用程序至关重要。

文章还讨论使用库简化API交互，提高开发效率，减少重复代码。最后，提供检查点和总结，强调构建和使用API的重要性，鼓励读者将所学知识应用于项目中。

通过本文，读者将获得构建和使用API的知识和工具，无论是本地开发还是探索艺术宝藏，都能提升开发技能和效率。

如何构建本地API

在 API 被部署到云之前，它可能是由像你这样的开发人员在本地开发的。你可以在本地计算机上创建 API。（当然，外部人员无法使用它，但这也不属于它的用途。）

设置 REST API 服务器

在命令行或终端上运行此命令：

npm install -g json-server

程序包 JSON Server 会创建一个“完全虚设的 REST API”服务器，用于原型制作和学习。

接下来，通过使用文本编辑器或 Visual Studio Code，在本地计算机上创建一个名为 db.json 的文件：

{

  "objects": [

    { "id": 1, "item": "Lise with a Parasol", "artist": "Pierre Auguste Renoir", "collection":"Museum Folkwang, Essen, Germany", "date":"1867"},

    { "id": 2, "item": "The Theatre Box", "artist": "Pierre Auguste Renoir", "collection":"Courtauld Gallery, London, England", "date":"1874"},

    { "id": 3, "item": "Dance in the City", "artist": "Pierre Auguste Renoir", "collection":"Musée d'Orsay, Paris, France", "date":"1883"},

    { "id": 4, "item": "Dance at Bougival", "artist": "Pierre Auguste Renoir", "collection":"Musée d'Orsay, Paris, France", "date":"1883"}

  ]

}

这个 JSON 文件是数据库的模拟版本。可以使用 json-server 来查询此数据。

查询数据库

在终端中，转到添加了 db.json 的位置，然后输入 json-server --watch db.json。服务器将在端口 3000 上运行。可以通过特殊格式的 URL 查询它。

尝试在浏览器的 URL 框中输入 http://localhost:3000/objects。你将看到数据库中所有对象，以纯 JSON 格式列出。

尝试使用 URL 查询此数据集：http://localhost:3000/objects/1 将显示 ID 为 1 的项目。

了解 REST API 调用

你可能已经注意到，API 调用由几部分组成。 REST API 调用的四个主要部分是终结点、方法、标头和数据（或主体）。

终结点是数据往返于网页的路由。它采用 URL 的形式，就像你之前用来查询数据集的 URL 一样。

方法是查询被设计用来执行的基于 HTTP 的操作。它可以采用 GET、POST、DELETE 或其他关键字的形式。 GET 方法通过终结点获取数据。 POST 方法通过终结点将数据从网页传递到服务器。 DELETE 方法从服务器中删除资源。

标头指定完成方法指定的操作类型所需的授权和身份验证。它们可能包括有助于对用户授权的 API 密钥。

数据包括 API 发送到服务器的对象。它通常采用 JSON 格式。

也可以按项名称进行搜索：http://localhost:3000/objects?item=Lise%20with%20a%20Parasol。

这种查询演示了以下两点：

需要对通过带有特殊字符的 URL 传递的查询设置格式，以处理标题中的空格。
你将通过格式 objects?item= 使用查询字符串查询对象的数据。此格式是用于查询的标准 REST API 格式。

使用浏览器的开发人员工具查看网页如何发送和接收数据。可以通过右键单击网页并选择“检查”或选择“F12”来找到它们。这些工具可用于 Web 开发的所有领域。但是，当你使用 REST API 调用时，可以深入到“网络”选项卡以观察你构建的 API 的行为方式。如果刷新浏览器，可以看到你在后台使用 GET 检索要在浏览器中显示的数据。

在我们的调用中，你通过 URL http://localhost:3000/objects 调用了一个终结点。

使用的方法是 GET。

目前调用中不需要任何标头。（稍后将详细了解标头。）

返回的数据与存储在 db.json 文件中的数据相同（由查询筛选）。

身份验证策略

大都会博物馆的 API 对公众开放，不需要身份验证。唯一的要求是用户“将请求速率限制为每秒 80 个请求”。这种开放程度对于 API 来说有点罕见。通常，管理面向公众的 API 的组织要求某种访问身份验证，以防止不必要的终结点过度使用。

如果 API 要求进行身份验证，则你不能通过 URL 调用直接调用以获取数据。需要改用“请求标头”，它是随请求一起发送的对象，并且使用 HTTP 调用。

使用 HTTP 协议进行身份验证

HTTP 协议为开发人员提供若干身份验证策略，包括“基本身份验证”和“持有者身份验证”。 “基本身份验证”本质上是不安全的，因为它要求直接通过请求标头传递用户名和密码。下面是一个示例：

Authorization: Basic abcdef12345==

“持有者身份验证”更常见。 “持有者身份验证”需要在身份验证调用之前获取的令牌，该令牌必须在请求标头中传递：

Authorization: Bearer <my-token>

使用 API 密钥进行身份验证

API 密钥在 API 体系结构中很常见。它们可能在各种位置出现：通过正文数据作为 JSON 传递，通过查询字符串发送或通过自定义标头或授权标头发送。

密钥是在代码和 API 之间形成握手的一种简便方法，但是它们本质上是不安全的。从理论上讲，任何人都可以使用密钥，只要他们可以通过网络调用拦截密钥。

提示

最好将 API 密钥存储在云中并通过调用环境变量的函数来访问它们。但是该方法超出了本教程的范围！

OAuth

使用 API 密钥很容易变得复杂，但这是为使用 API 进行身份验证的最常用方法。进行身份验证并使用 API 的另一种方法是通过 OAuth。 OAuth（尤其是版本 2）提供更精细的身份验证策略。用户被定向到 API 的站点，然后完成 OAuth 为启用访问所允许的许多流之一。可能存在多种情况。但是 OAuth 基本上支持 API 密钥的创建，并使用密钥对令牌进行身份验证，从而支持对有限的操作进行有限的 API 访问。这样，用户可以在 Web 调用中使用访问令牌，确保针对特定用途和特定时间段访问 API 的各个部分。

API 密钥与访问令牌的不同之处在于，密钥提供授权但不提供身份验证。访问令牌提供一种更安全的方法来访问敏感终结点。

在下一个单元中，你将查询使用 OAuth 2 的 API：史密森尼博物馆的库珀·休伊特国家设计博物馆

查询大都市API

到目前为止，你已构建可以在本地计算机上使用的 API，以便更好地了解 API 的工作方式。现在，你将查询第一个 API，以在真正的第三方 API 中搜索对象：纽约大都会博物馆 API。

现代博物馆藏品管理的一个奇妙之处在于，目前正在进行的藏品数字化和在线化工作也使业余艺术爱好者可以访问其数据。美国的史密森尼博物馆、阿姆斯特丹的国立博物馆和美国的芝加哥艺术学院等许多博物馆都在开放它们的藏品，让公众可以通过虚拟方式接触它们。

研究 API

研究第三方 API 的使用的第一步是查看其文档。查看博物馆提供的 API 文档。

要考虑的另一件事是权限。通读要使用的所有第三方 API 的使用条款，以确保要执行的操作是可以接受的。大都会博物馆的条款和条件页面是一个不错的开始。因为该博物馆采用了知识共享零许可证，所以数据集没有版权。该许可证使临时用户可以更轻松地使用 API。

你不需要 API 密钥即可使用此 API，因此可以通过格式标准的 URL 查询使用 GET 请求来访问其集合的许多元素。通过访问给定的 URL，可以在浏览器中使用大都会博物馆的 API。这是使用 API 的最简单方法。在后面的单元中，你将了解如何使用代码调用 API。

查询 API

大都会博物馆的终结点或用于查询对象的 URL 是多个对象、单个对象、部门和搜索。

此 API 的设计表明，用户应该搜索集合，然后深入到对象组和各个对象以获取更多细节和信息。 API 正在逐步构建。选择包含部门终结点可能表明数据的构造方式以及用户搜索数据的方式。

假设你对武器和盔甲感兴趣。可以查询部门终结点以获取该部门的 ID：

https://collectionapi.metmuseum.org/public/collection/v1/departments

如果将该链接粘贴到浏览器中，会发现武器和盔甲部门的部门 ID 为 4。现在，你已获得了一些信息，可以用来在集合中找到有趣的项目。为此，可以使用“搜索”终结点。

由于该 API 尝试返回可控制的数据量，鉴于 5,000 年艺术史涉及大量藏品，因此仅按照 DepartmentId 进行搜索不会成功。你需要通过该部门内的关键字来缩小搜索范围。

这种缩小范围活动要求你在 URL 中使用查询参数来访问终结点。如果查看文档，你会看到预期的格式是向终结点追加 ?q=keyword(s)。所以，如果只查找银制浮雕武器和盔甲物品，请将此字符串粘贴到浏览器：https://collectionapi.metmuseum.org/public/collection/v1/search?departmentId=4&q=embossed%20silver。返回了二十七个项目。

此查询提供用于检索返回的对象的信息。若要查看组中的第一个对象，请转到以下终结点：https://collectionapi.metmuseum.org/public/collection/v1/objects/626019。返回的数据显示 1800 年以来壮观的盔甲装束（配有制型纸头盔）。可以想象战时一方穿上它的样子！

这个服装头盔于 1988 年被大都会博物馆收购，目前存放在武器和盔甲馆。

总结

大都会博物馆的 API 有条理且易于访问，可以作为你构想如何在网站中使用 API 的一个好起点。可以使用 search 终结点和查询参数构建搜索。可以在 department 中查询一组 objectid，并在其上循环以创建一个有趣对象的列表。可以深入而详细地浏览该集合，而无需接触甚至理解其基础数据库。这就是出色的 API 的强大之处！

查询Cooper Hewitt API

现在，你已经在大都会博物馆发现了一些有趣的藏品，下面让我们看一下另一个博物馆 API：Cooper Hewitt API。库珀·休伊特国家设计博物馆是史密森尼博物馆的一部分。它是美国的国家设计博物馆。从戴森风扇到古董鞋，它的藏品侧重于有趣的著名设计。

若要访问 API，你需要一个访问令牌，或者同时需要一个访问令牌和一个充当其验证器的 API 密钥。该 API 允许用户使用一次性访问令牌访问终结点以进行单独访问。但是如果要使用代码查询 API，需要两个元素。

创建令牌和密钥

请转到 API 主页并创建帐户。创建帐户后，可以自行创建密钥和访问令牌。将文本文件中生成的令牌保存在本地计算机上的安全位置。

备注

为什么要同时创建访问令牌和密钥？该 API 使用 OAuth 2，OAuth 2 需要令牌来监视和限制对该 API 的访问。 API 密钥与访问令牌一起使用，以确保你有权以通过令牌设置的方式访问 API。

创建令牌并使用 API 密钥对其进行身份验证之后，可以开始在测试 API 调用的 URL 中发送令牌。让我们看看在库珀·休伊特设计博物馆中可以找到什么！

查询 API

假设你对新艺术风格感兴趣，并且想看看那个时代的藏品中存在哪些对象。通过该 API，可以获取该时代的 ID，并对其进行查询以获取针对该时代指定的藏品的 URL。

备注

对于以下查询，获取如前所述的访问令牌，并将其粘贴到查询中的指定位置。

若要查找新艺术风格的对象，请按以下方式查询 API：https://api.collection.cooperhewitt.org/rest/?method=cooperhewitt.periods.getList&access_token=<your-token>&page=1&per_page=100。该查询指定需要追加要检索的页面以及每页返回的元素数。

查询 API 时，响应中将返回一个 URL，其中包含可供精读的新艺术风格对象列表（包括一些著名的 Mucha 海报）：https://collection.cooperhewitt.org/periods/35417231/。可以看一看。通过查询此 API，还能发现其他哪些时代？

处理响应

在许多情况下，了解 RESTful API 发送回的状态代码很重要。如果出现服务器错误，该怎么办？如果没有要发送回的数据，该怎么办？如果出现身份验证错误，该怎么办？如果发生上述任何一种情况，关注代码都是很有用的，这样就可以告诉前端用户存在问题。

尝试查询

例如，在浏览器中尝试以下查询：https://api.collection.cooperhewitt.org/rest/?method=cooperhewitt.periods.getList&access_token=xxxxx&page=1&per_page=100。

API 将返回代码 400：这是一个“错误请求”错误。这是 URL 中的访问令牌无效导致的。

了解状态代码

可能遇到的常见访问代码包括：

200 – 正常。请求已成功。
204 – 无内容。
301 – 永久移动。
400 – 错误的请求。
401 – 未授权。
403 – 已禁止。
404 – 未找到。
500 – 内部服务器错误。

请务必了解状态代码，以便可以在客户端代码中很好地处理这些代码。通常，200 代码表示“一切正常”，可以继续显示查询结果。该代码也可用于对错误进行分类并显示处理错误的适当消息。

使用库

通过浏览器的 URL 发送查询来测试 API（将访问令牌填充的查询字符串作为补充）是有用的。但是在生产应用中，可能需要进行更复杂的 API 调用，将各种数据组合在一起形成查询。

因此，许多开发人员依赖标准化 API 使用过程的库。对于 JavaScript 开发人员来说，Axios 是一个绝佳的选择。 Python 程序员可能会使用请求。使用 PowerShell？尝试 RestMethod。

使用 URL 进行查询

假设你对收音机闹钟非常热衷，并且对库珀·休伊特博物馆中设计精良的示例藏品很感兴趣。你可以查看该博物馆的 API 文档。你会看到，如果想要分页结果并且结果中仅包含图像，可以使用这种格式的 API 访问令牌来构建查询：

https://api.collection.cooperhewitt.org/rest/?method=cooperhewitt.search.collection&access_token=<your access token>&query=clock%20radio&has_images=true&page=1&per_page=100

出现的第一个示例是 20 世纪 50 年代的以下精巧示例：

通过在本地开发环境中运行以下代码片段，尝试使用库来调用 Cooper Hewitt API：

var axios = require('axios');



var config = {

  method: 'get',

  url: 'https://api.collection.cooperhewitt.org/rest/?method=cooperhewitt.search.objects&query=clock%20radio&page=1&per_page=100&access_token=yourtoken',

  headers: { }

};



axios(config)

  .then(function (response) {

    console.log(JSON.stringify(response.data));

  })

  .catch(function (error) {

    console.log(error);

  });

通过使用适合你首选编程语言的库，可以在基于用户交互（例如按钮单击）编写函数脚本时，更好地控制如何在代码中使用 API。

使用方法写入终结点

类似于这些博物馆示例的许多第三方终结点不允许使用 POST 写入其数据库。这些数据库不是事务性的。但是你可以练习使用方法来写入自己的数据。

返回到你之前在本模块中创建的 db.json 文件。可以将数据写入此数据库。

使用终端，cd 到 db.json 文件的位置，然后输入 json-server --watch db.json。服务器将在端口 3000 上启动。可以将 GET 用于对象集合 localhost:3000/objects，使用 Postman 对其进行查询。

可以通过设置标头值 'content-type': 'application/json' 并通过字符串化的 JSON 对象来写入此集合：

var axios = require('axios');

var data = JSON.stringify({"id":5,"item":"The Fiancés","artist":"Pierre Auguste Renoir","collection":"Wallraf–Richartz Museum, Cologne, Germany","date":"1868"});



var config = {

  method: 'post',

  url: 'localhost:3000/objects',

  headers: { 

    'content-type': 'application/json'

  },

  data : data

};



axios(config)

  .then(function (response) {

    console.log(JSON.stringify(response.data));

  })

  .catch(function (error) {

    console.log(error);

  });