了解基于 API 的平台：产品经理指南

今天构建数字产品是将无数的各种后台系统与客户接触点和设备集成在一起。 聘请软件团队将它们连接到一个工作解决方案中的成本可能会飙升。

这就是为什么现代产品经理在选择供应商时通常将集成能力放在首位，这可能归结为选择暴露 API 的系统。 API 是什么以及如何在不让您的技术团队参与的情况下对其进行测试？ 继续阅读。

拥抱数据：为什么我们需要 API

客户数据改变了企业的运作方式。 如果正确收集和转移，它们可以帮助公司提高客户获取和保留率，最终导致收入激增。

但是数据处理是一项乏味的工作。 这就是商业利用计算机科学的原因。 在 1990 年代，自动化最耗时的数据任务的数据库在营销部门中大受欢迎。 这导致了营销策略构思方式的巨大转变——这种转变被称为数据驱动方法。

不过，数据库有一个主要缺点。 为了使它们有价值，公司需要聘请软件工程师。 他们是知道如何将大量数据转化为有效见解的英雄。 他们也是保护数据完整性的卫士，从而确保系统面向未来。

但是软件工程师的成本很高，而且他们的通信接口需要付出努力。

当数据收集渠道的数量跨越多个部门甚至外部公司时，数据库及其运营商就成为了瓶颈。 企业需要找到一种访问数据存储的自动化方式。

这就是 API 优先系统的想法的起源。

没有技术术语的 API 实际上是什么

API 优先系统，今天通常简称为 API（应用程序可编程接口） ，是确保其他系统可以以统一和安全的方式访问其数据的应用程序。

没有计算机科学等级，应用程序可编程接口并没有真正敲响警钟。 让我们看一个更具体的解释。

到目前为止，我在网上找到的最好的类比之一是 Taija 写的：

“如果你作为顾客去餐厅，你是不允许进入厨房的。 你需要知道什么是可用的。 为此，您有菜单。 查看菜单后，您向服务员点菜，服务员将其传递给厨房，然后由服务员提供您要的东西。 服务员只能提供厨房能提供的东西。

我见过的最好的 API 类比：拿一家餐馆。 菜单是 API，您的订单是 API 调用，厨房的食物是响应。

— Aarthi 发财！ (@AarthiD) 19. 2013 年 12 月

这与 API 有什么关系？ 服务员是 API。 你是一个寻求服务的人。 换句话说，您是 API 客户或消费者。 菜单是解释您可以从 API 中请求什么的文档。 例如，厨房是服务器； 一个只保存特定类型数据的数据库——无论买家为餐厅购买的任何食材、厨师决定他们将提供什么以及厨师知道如何准备什么。”

再说一遍：

• 厨房
  数据库，不允许客户保护数据完整性。
• 服务员
  API，一个知道如何在不中断其功能的情况下从数据库提供数据的中间人。
• 顾客
  想要获取数据的外部系统
• 菜单
  数据格式参考外部系统必须使用来执行它们的操作。
• 命令
  实际的单个 API 调用。

以目前的技术状态，仍然需要软件开发人员“下订单”。 但它的速度更快（阅读：更便宜），因为菜单，就像麦当劳一样，在世界范围内或多或少是标准化的。

所以现在，我们将穿上软件开发者的鞋子，尝试调用一个示例 API。 别担心； 我们不会超越学校的计算机科学课程。

您的天气应用程序如何获取数据：API 基础

我们将了解您的天气应用程序如何知道当前温度。 通过这种方式，我们将了解如何通过 Internet 与系统通信的基础知识。

我们需要的：

• 天气数据库
• 浏览器
• 一点意志力

而已！ 当今的技术使测试 API 变得容易，而无需大型开发人员工具。

当然，当您想要创建一个完整的集成时，情况就不同了。 紧要关头，您需要了解更高级的工具和编程语言，但对于测试/概念验证，这种设置就足够了。

因此，让我们尝试获取您所在城市的当前温度指数——或者，用编码人员的话来说——让我们调用第一个 API 调用。 毕竟，它归结为向服务器发送一些文本并接收消息作为交换。

API 请求剖析

在本文中，我们将使用 https://openweathermap.org API。 访问该站点并尝试检查多个位置的天气状况。 希望你今天在卡托维兹感觉比我好：

正如您可能已经猜到的那样，该网站正在调用 API 来获取数据。 开发人员以每次按下搜索的方式实现它，应用程序在后台敲开 API 的门并说“给我 <city> 温度”。

让我们戴上黑客的帽子，看看这个网站用你的浏览器调用的 API 调用。 您可以在浏览器中使用开发者工具来查看幕后发生的事情：

1. 在 Chrome 中，转到菜单 → 更多工具 → 开发者工具；
2. 切换到网络选项卡；
3. 尝试在上面的小部件中检查不同城市的温度；
4. 在底部的列表中，您会注意到已调用的链接：
   

   

   
   如果您复制链接，您可以看到它包含位置名称和其他几个参数。
   

    https://openweathermap.org/data/2.5/find?callback=jQuery19103887954878001505_1542285819413&q=Katowice&type=like&sort=population&cnt=30&appid=b6907d289e10d714a6e88b30761fae22&_=1542285819418

5. 当您将链接粘贴到浏览器的地址栏时，您应该会看到 API 回复：
   

    jQuery19103887954878001505_1542285819413({"message":"accurate","cod":"200","count":1,"list":[{"id":3096472,"name":"Katowice","coord":{"lat":50.2599,"lon":19.0216},"main":{"temp":281.69,"pressure":1031,"humidity":61,"temp_min":281.15,"temp_max":282.15},"dt":1542285000,"wind":{"speed":3.6,"deg":50},"sys":{"country":"PL"},"rain":null,"snow":null,"clouds":{"all":90},"weather":[{"id":804,"main":"Clouds","description":"overcast clouds","icon":"04d"}]}]})

6. 有点乱，但是如果你取出括号的内容，用数据格式化程序运行它，你会看到一个有意义的结构：
   

    { "message":"accurate", "cod":"200", "count":1, "list":[ { "id":3096472, "name":"Katowice", "coord":{ "lat":50.2599, "lon":19.0216 }, "main":{ "temp":281.69, "pressure":1031, "humidity":61, "temp_min":281.15, "temp_max":282.15 }, "dt":1542285000, "wind":{ "speed":3.6, "deg":50 }, "sys":{ "country":"PL" }, "rain":null, "snow":null, "clouds":{ "all":90 },

7. API 的回复是一个包含当前天气状况信息的数据结构——您应该可以轻松解密大部分参数。 这种数据格式称为 JSON 。 这是一个重要的符号，因为大多数现代 API 都使用它。 这堆标识符和括号有一个目的——应用程序解析结构良好的消息比解析随机放置的文本更容易。

解释一下我们刚刚在这里所做的事情。

Open Weather Map 网站背后的 Web 应用程序从 API 获取数据并将其显示在网站上。

每次您输入城市名称并按搜索时，网站都会连接到具有特定链接的服务器，该链接包含城市名称作为参数。

技术术语中的同一句话：网站背后的应用程序向API 端点发送请求，提供城市名称作为参数。

然后，API 使用JSON格式的文本消息回复（发送API 响应）。

要创建 API 请求，您需要将其地址放在一起。 是的，地址是一个很好的类比。 要运送东西，您需要向快递员提供：

• 城市，
• 街道和门牌号，
• 有时会提供一些关于如何到达办公室的额外信息。

而且，要连接到 API，以此类推，您需要：

• https://openweathermap.org/ （链接）城市或根端点——在我们的例子中，一个起点，一个你想连接的服务器的互联网地址。
• data/2.5/find (link) 街道号码或路径——决定了你想从 API 获取的资源。
• ?callback=jQuery19103887954878001505 1542285819413&q=Katowice&type=like&sort=population&cnt=30&appid=b6907d289e10d714a6e88b30761fae22& =1542285819418（链接）的额外信息或查询参数-让API服务器

这就是 API 的设计方式。 对于单个供应商，根端点通常保持不变，然后您需要弄清楚哪些路径和查询参数可用，以及 API 开发团队在它们后面放置了哪些信息。

现在让我们把黑客的帽子戴得更紧一点。 在我们的例子中，并非所有查询参数都是获取天气数据所必需的。 尝试删除问号 ( ? ) 后的不同参数并检查 Weather API 如何回复。

例如，您可以从请求链接中删除callback开始：

 https://openweathermap.org/data/2.5/find?callback=jQuery19103887954878001505_1542285819413&q=Katowice&type=like&sort=population&cnt=30&appid=b6907d289e10d714a6e88b30761fae22&_=1542285819418

结果：

 https://openweathermap.org/data/2.5/find?q=Katowice&type=like&sort=population&cnt=30&appid=b6907d289e10d714a6e88b30761fae22&_=1542285819418

如果您与其他人一起玩，您会发现其中一些也是可选的。 实际上只有q和appid是强制性的：

 https://openweathermap.org/data/2.5/find?q=Katowice&appid=b6907d289e10d714a6e88b30761fae22

你怎么知道什么是强制性的，什么是可选的？ 首先，您如何知道从何处获取根端点和路径？

API 文档：开始前必读

您总是需要先查看 API 文档，以了解如何以正确的方式构建您的请求。

在我们的例子中，文档 https://openweathermap.org/current 显示了可用的端点。 它还解释了所有响应数据字段——因此您甚至可以在发送请求之前找到 API 将回复的信息。

一个好的 API 文档提供了关于如何创建简单请求和转向更高级内容的快速入门教程。 幸运的是，Open Weather API 有一个，我们现在就要使用它。

从头开始创建 API 调用

让我们总结一下我们的发现。 我们已经向 API 发送了一个请求。 通过嗅探 OpenWeatherMap 在幕后所做的工作，我们找到了正确的链接。 这种方法称为逆向工程，通常很难或根本不可能。

此外，大多数时候，API 提供商会禁止用户过度使用此选项。 这就是为什么我们应该学习如何按照规则（即文档）“调用”API。

一种方法是对其进行编码。 但由于我们不是编码员（还没有！ ），我们将使用使这更容易的工具。 如此简单，即使是软件开发人员也可以将它放在他们的工具带下。

正如所承诺的，我们不会离开浏览器。 但是我们需要安装一个扩展程序（仅限 Chrome）——Postman。 这个简单的插件将您的浏览器变成一个 API 连接器。

好的，现在我们有了一个工具，让我们看一下文档，看看我们如何获取特定城市名称https://openweathermap.org/current#name的当前天气状况。

文档说我们应该使用以下端点： api.openweathermap.org/data/2.5/weather?q={city name}

当我们分解它时，我们会得到以下元素：

• 根端点： api.openweathermap.org
• 路径： data/2.5/weather
• 查询参数： q={city name} （这个概念意味着我们应该用特定的城市名称替换大括号）

让我们把它放到 Postman 中。 该过程归结为三个简单的步骤：

1. 单击顶部菜单中的“请求”。
   

   

2. 命名您的请求并在底部的部分中提供目录名称。

   

3. 粘贴您要调用的 API 端点，单击“发送”，您应该会在“响应”部分看到 API 响应：

   

恭喜！ 您刚刚成功呼叫了您的冷杉……等一下！ 让我们注意API响应：

它不是我们以前见过的充满天气信息的 JSON。 401 和无效的 API 密钥到底意味着什么？ 我们的文档有错吗？

验证

未经您的许可，您不会让任何人进入您的鸡尾酒柜，对吗？ 同样，API 提供商也希望控制其产品的用户，以保护其免受恶意活动的侵害。 什么是恶意活动？ 例如，同时发送多个 API 请求，这会使服务器“过热”并导致其他用户停机。

如何控制访问？ 就像你保护你的饮料一样！ 通过使用密钥——API 密钥。

如果您访问 Weather API 文档中的如何开始指南，您会注意到如何获取密钥。 立即注册并检查您的收件箱。

那么现在的问题是如何使用密钥？ 根据文档，这很容易，只需将密钥复制并粘贴到端点 URL 的末尾（不带大括号）。

 api.openweathermap.org/data/2.5/weather?q=Katowice&appid={your API key}

然后再次点击发送。 在这里，我们现在可以看到 API 响应！

但是您可以使用 Postman 从 API 中获得更多信息。 准备好成为真正的 API 黑客了吗？

API 参数：获取定制响应

通常，API 端点具有一些实用功能，可用于调整 API 响应，例如，如果您需要更好的数据格式或希望以特定顺序获取数据。 这些选项通常隐藏在您可以在文档中找到的一些参数后面。

查询参数只是您在端点地址添加的结构化文本，具有以下模式：

1. 路径后的问号 ( ? )，
2. 参数名称，
3. 等于 ( = ) 符号，
4. 参数值，
5. 与号 ( & ) 和其他符号遵循第 2-4 点（通过这种方式，您可以添加任意数量的参数）。

以我们的第一个请求为例：

 https://openweathermap.org/data/2.5/find?q=Katowice&appid=b6907d289e10d714a6e88b30761fae22

重要提示：查询参数的顺序无关紧要。

 ?q=Katowice&appid=b6907d289e10d714a6e88b30761fae22

以上与以下相同：

 ?appid=b6907d289e10d714a6e88b30761fae22&q=Katowice

如前所述，查询参数在 API 文档中进行了描述。 以下天气 API 文档摘录向您展示了如何以不同的单位（英制或公制）获取温度：

尝试使用 Postman 发送这两个选项以查看结果差异。 请记住在端点地址的末尾添加您的 API 密钥。

注意：总是花一些时间研究文档并找到可以为您或您的开发团队节省大量时间的参数。

API 请求选项：如何向 API 发送数据

到目前为止，我们一直在从 API 获取信息。 如果我们想在 API 后面的数据库中添加或修改信息怎么办？ 请求方法就是答案。

让我们再看看 Postman。 您可能已经注意到 API 端点地址旁边有一个大写的 GET 标签。 这代表四种请求方法之一。 GET意味着我们想从 API 中获取一些东西（感谢船长），这是一个默认选项。 还有哪些其他选择？

还在纠结？ 让我们转到示例。

API POST：如何在 API 中创建记录

我们无法使用 Wea​​ther API 创建或更新任何内容（因为它是只读的），因此我们需要找到一个不同的用于测试目的。

让我们提出一些更面向业务的示例。 我们将模拟以下场景：

如果下雨，请为您的客户制作一张“振作起来”的折扣券。

我们将使用 Voucherify，它提供了一个 API，用于为任何电子商务系统创建和跟踪促销活动。

免责声明：我是 Voucherify 的联合创始人。 我很高兴回答您有关设计和实施数字促销的问题，当然还有我们的 API 。

我们已经知道如何从前面的示例中获取它们，所以让我们专注于创建凭证：

1. 正如我们所说，我们应该始终从文档开始。
2. 快速入门指南告诉我们获取 API 密钥。
   注意：您可以使用快速入门指南中的测试密钥，而不是创建帐户——我们将在一分钟内向您展示如何操作。
3. 现在，让我们了解如何创建折扣券。 在 Voucherify 中，这种促销被表示为“优惠券”。
4. 从文档中，您将了解到要创建凭证，您需要调用 POST 方法到/vouchers端点。
5. 在 Postman 中创建一个新的请求。
6. 将方法更改为 POST。
   

   

7. 粘贴 Voucherify 端点https://api.voucherify.io/v1/vouchers/并单击发送。
   

   

8. 哦，快照，我们无权调用此端点。 您可能已经猜到了，我们需要提供 API 密钥。
   
   Voucherify 的做法略有不同。 而不是将它们作为查询参数，您应该将它们放在标题中。 这是一种常见的方法，因为以这种方式实现和维护键比将它们附加为查询参数更容易。
   
   如图所示添加密钥，然后单击发送。 请注意，Voucherify 需要两个密钥。 以下是您可以用于本教程目的的：
   X-App-Id: 8a824b12-0530-4ef4-9479-d9e9b9930176 X-App-Token: 9e322bac-8297-49f7-94c8-07946724bcbc

   

9. 我们收到另一条错误消息，这次它说有效负载不能为空。
   

   

   
   什么是有效载荷？ 与 GET 的情况一样，我们想要检索一些信息，使用 POST 我们需要发送一些东西，我们发送的消息称为有效负载，它通常是一个 JSON 文件。
   
   现在 Voucherify API 抱怨我们没有提供一个，这意味着它不能创建一个凭证，因为我们没有告诉它应该创建什么样的凭证。 所以现在怎么办？ 回到文档！
10. 让我们找出这个请求需要什么样的信息才能成功。 我们可以在列表中看到很多选项。
    

    

    
    一个参数（类型）是必需的，另一个是可选的。 假设这将是 20% 的折扣，适用于前 100 位客户，即日到期。 现在我们需要找到负责此折扣功能的参数，并将它们组合成对 Voucherify API 不稳定的格式。 正如您在上面的示例中看到的，您应该使用的 JSON 表示法如下所示：

     { "type":"DISCOUNT_VOUCHER", "discount":{ "percent_off":20.0, "type":"PERCENT" }, "expiration_date":"2018-12-03T23:59:59Z", "redemption":{ "quantity":100 }

11. 要在 Postman 中设置有效负载，请将 JSON 消息粘贴到正文选项卡中。 从可用负载格式列表中选择“原始”类型和 JSON，然后使用发送确认。
    

    

12. 瞧！ Voucherify 已成功创建了我们的 20% 折扣优惠券（因为我们正在使用测试帐户，所有生成的代码都以“voucherify.io-”前缀开头）。 营销团队现在可以与客户共享代码，并且 Voucherify 将在他们来您的商店兑换它时自动验证它。
    

    

    
    但是我们怎么知道这是一个成功的请求呢？ 首先，我们可以看到 Voucherify 向我们发送了一条消息，根据他们的文档，该消息看起来像是一个正确的 API 响应。 其次，Postman 显示状态200 OK——这意味着我们的请求成功。 为什么是 200 以及状态如何？

API 状态代码和错误消息

您将与之交互的大多数 API 都是基于 HTTP 的。 HTTP 是一种标准化 Internet 上各种客户端应用程序和服务器之间的通信的协议。

HTTP 的关键元素之一是状态码。 通过了解您（或您实际实现的系统）的状态代码，可以立即了解您的请求发生了什么。 当您输入错误的链接时，您可能会遇到最流行的状态代码之一 - 404

但是还有更多，最终用户通常看不到它们。 它们的范围从 100+ 到 500+。 一般来说，数字遵循以下规则：

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

如果您可以再次执行这些步骤，您会看到当我们没有提供 API 密钥时，Voucherify 回复了 401 Unauthorized。 或 400 Bad Request 当没有创建凭证请求所需的有效负载时。 最后，我们收到 200 作为 API 调用成功的标志。

如果您对 HTTP 状态码的含义感到好奇，那么没有比 HTTP Cats（或者这篇文章）更好的地方了。

概括

不断增长的数据量和对构建产品速度的需求推动 API 成为数字团队的通用语言。 要基于 API 优先系统设计系统，请确保您了解供应商的产品。 这个动手测试指南是这样做的一个很好的起点。 它将帮助您在将 API 功能交给您的教学团队之前探索 API 功能，从而节省他们的精力 - 以及您的精力。

延伸阅读

• “面向非开发人员的电子商务 API 简介”，Scott Brinker
• “超越 Headless CMS — 认识 Headless Commerce”，Michal Sedzielewski，Voucherify
• “如何使用 API 优先平台更快地构建您的网站”，Michal Sedzielewski，Medium
• “如何使用您的 API 优先平台让您的原型产品为生产做好准备，”Michal Sedzielewski，Medium
• “如何使用云更快地构建应用程序”，Michal Sedzielewski，Hacker Noon