多数产品新人尽管已精通业务，却仍难免遭开发团队吐槽“需求过多，接口太多难以完成”。对此，他们困惑不解，甚至无法理解对于他们而言显而易见的“接口”究竟为何物。实际上，除可见文案与按钮外，系统中还存在诸多隐含逻辑链条——即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 协议》，转载必须注明作者和本文链接