多数产品新人尽管已精通业务，却仍难免遭开发团队吐槽 “需求过多，接口太多难以完成”。对此，他们困惑不解，甚至无法理解对于他们而言显而易见的 “接口” 究竟为何物。实际上，除可见文案与按钮外，系统中还存在诸多隐含逻辑链条 —— 即 API（应用程序接口）。本文将以 API 基础知识为依托，结合产品经理实际业务情境，助您深入理解并有效运用 API，从而实现与开发团队的高效协作。

API 是什么？#

API，即 Application Program Interface，应用程序编程接口，是一组定义的规则，使不同的应用程序能够相互通信。它充当处理系统之间数据传输的中间层，使公司能够向外部第三方开发人员、业务合作伙伴和公司内部部门开放其应用程序数据和功能。

图片来源：CSDN@tbprice

API 的工作原理其实很易于理解。我们通过微信支付来解释，就可以轻松地了解 API 工作原理。当我们在点外卖时，系统会提示我们 “使用微信付款” 或其他类型的第三方付款方式。该付款功能就是依赖 API 来完成的。当我们点击付款按钮时，API 会调用以检索信息（也称为请求）。该请求是通过 API 的统一资源标识 (URI) 从应用程序处理到 Web 服务器，包括请求动词、标头，有时还包括请求正文。

从产品网页收到有效请求后，API 会调用外部程序或 Web 服务器，即第三方支付系统。服务器向 API 发送包含所请求信息的响应。API 将数据传输到初始请求的应用程序，此处为产品网站。虽然数据传输会根据所使用的 Web 服务而有所不同，但请求和响应都是通过 API 发生的。用户界面上看不到这些传输，这意味着 API 在计算机或应用程序内交换数据，在用户看来是一种丝滑的无缝连接。

API 怎么分类？#

随着沟通场景的变化，API 的分类维度也会不同：

• 按照 API 提供方划分：自有 API、三方 API（例如：身份认证、短信服务、支付服务、AI 大模型等)。
• 按照 API 技术属性划分：系统 API（例如：缓存、定时、通知、监控等）、业务 API（会员 API、商品 API、内容 API、交易 API 等）、平台 API（单独登录 API、搜索 API、AI 客服 API 等）。
• 按照 API 调用方式划分：同步 API、异步 API。
• 按照 API 颗粒度划分：服务类 API（例如：美团外卖 API、淘宝商城 API、京东快递 API 等）、功能类 API（例如：短链 API、归属地 API、企业认证 API 等）。
• 按照 API 是否对外开放划分：内部 API、开放 API。

产品经理在哪些场景需要设计 API？#

• 在开发基于互联网的应用时（SPA 应用、APP 应用、小程序、智能设备应用等），技术架构基本都是客户端 - 服务器模式，此时服务端基本都是 API，产品经理只需要描述业务即可。
• 在给上下游提供技术接口时，基本都以 API 方式提供，此时产品经理需要设计 API、定义 API。
• 在企业服务货币化时，以 API 方式提供，此时产品经理需要设计 API、定义 API、定价 API 等。

产品经理在哪些场景会用到三方 API#

由于成本因素、数据或资源持有因素、技术能力因素等，企业在研发数字化系统时，不可能所有服务都自研，也不会都使用开源代码自建，大量使用三方 API 成为必然选择。

通用基础场景，例如登录：在设计应用程序时，最基础的功能就是用户的登录功能，而用户不需要在每个软件都单独注册账号，而是可以使用微信、QQ 和支付宝等账号来登陆应用程序。类似的场景还包括 KYC 认证、单点登录、安全管理、资金收付、社交分享、用户沟通等。

使用平台资源场景，例如旅行预定：各大旅行平台软件的基础功能是汇总航班和酒店等信息，展示在不同的日期下的不同价格。通常这些数据来自于上千个网站和主页，这项服务也是通过 API 来完成的。类似的场景还包括快递及物流、外卖平台、几大电商平台等，企业必须用到三方 API。

使用三方技术能力场景，例如 AI 大模型：AI 大模型是 24 年的新宠，大部分企业无法自研，将会以使用为主。类似的场景还包括云计算技术、区块链技术、大数据技术、存储技术等。

使用企业服务类 SaaS 应用，例如 CRM：CRM（客户关系管理工具）等平台通常包含许多内置 API，使公司能够与他们已经使用的应用程序集成，例如消息传递、社交媒体和电子邮件应用程序。这大大减少了在不同应用程序之间进行切换以执行销售和营销任务的时间。类似的场景还包括财务 SaaS、人力 SaaS、办公 SaaS、营销 SaaS 等。

产品经理如何写好 API 产品文档？#

产品 PRD 主要的阅读对象是后端开发（RD）、前端开发（FE）、交互设计师（UI、UE）、测试（QA），他们会在 PRD 中获取自己需要完成的工作目标，并以此为基础进行方案设计。

在前文中我们学习了 API 知识，拥有了和开发人人员沟通的语言，现在我们需要将这些知识转化为我们对需求的描述，以便开发人员读懂我们的需求。

以下是一个具体案例：假设我们是一家电子商务平台的产品经理，现在需要设计一个新的 API，用于实现用户订单的创建功能。在编写 API 产品文档时，我们需要考虑以下几个方面。

1. 接口功能描述：首先，我们需要明确这个 API 的功能是什么，即用户订单的创建。在文档中详细描述该功能，包括输入参数、输出结果等。
2. 参数说明：对于订单创建功能，可能涉及到用户信息、商品信息、支付信息等参数。在文档中列出所有可能的参数，并说明每个参数的含义、类型、是否必填等信息。
3. 请求示例：提供几个具体的请求示例，展示开发人员如何调用该 API 以实现订单创建功能。示例应该覆盖不同情况下的参数组合，以确保开发人员理解清楚。
4. 返回结果：说明调用 API 后会得到什么样的返回结果，包括成功时和失败时的情况。对于成功的情况，应该详细说明返回的订单信息；对于失败的情况，应该说明失败的原因。
5. 错误码定义：定义可能出现的错误码及其含义，以便开发人员在调用 API 时能够根据错误码快速定位问题。
6. 安全考虑：对于涉及用户隐私或支付等敏感信息的 API，需要考虑安全性。在文档中说明如何保障用户信息的安全，例如使用 HTTPS 协议、参数加密等。

通过以上的详细描述，产品经理可以编写出清晰、完整的 API 产品文档，有效地传达需求给开发人员，并确保他们能够正确地实现所需功能。

如何就 API 和开发团队们沟通？#

统一的标准

沟通是项目进行的必备条件。产品经理在和开发小伙伴对接之前，就应当注意统一标准和方式，以便更好修改和跟进。

统一的平台

借助 iPaaS 平台、API 网关等现代化平台，企业先在底层技术层面建立实现的一致性，利用平台能力，忽略技术复杂性，专注于业务自身。

统一的工具

技术人员在开展 API 设计时，可以借助 API 设计工具来实现产品经理、开发人员、测试人员在一个共同视图上进行沟通、编程、升级与维护。例如 Postman 等工具。

本作品采用《CC 协议》，转载必须注明作者和本文链接