本文来自微信公众号 ”汪童学“，作者：顺顺顺，纷传经授权发布。
01
为什么产品经理要写接口需求？
我目前就职的公司，整个集团的产、研人员多大上千人，业务庞大且复杂。在这样的环境，当某个需求涉及到与其他业务线有数据上的交互时，需要产品经理经理去调研需求、并输出接口需求文档。这样的事情，对于像我这样的公司老人来讲，是非常可以理解的。但是新加入公司或团队的产品，经常会发出一个疑问“为什么产品经理需要写接口需求文档”？
在小团队中，业务划分不清晰，所有业务共用一个产、研团队，产品、开发对全局的业务和业务涉及的数据流会比较熟悉。在这种环境下，假设某个需求的方案，在实现过程中需要基于本业务系统和其他业务系统的数据来实现，就不需要产品经理去写接口需求，开发可基于对需求的理解，自行完成接口的需求梳理和接口的实现。
在大团队中，首先在组织架构上会根据不同的业务线，划分不同的业务部门和不同的产研团队，在这样的组织中，每个业务线的开发一般情况下只负责业务范围内的需求，不会交叉负责其他业务线的需求，从而就会造成不熟悉其他业务线的业务与数据流的现象。在这种环境下，如某个需求的方案，在实现过程中需要基于本业务系统和其他业务系统的数据来实现，就需要产品经理去调研并输出接口需求。
举个例子：
营销团队的某个营销活动，需要基于用户的某些信息去判断用户是否可以参与活动时，就需要营销团队产品经理去了解用户业务的业务、数据、如何获取，并向开发提出接口需求并提供接口需求说明。据我所了解的情况，很多业务庞大且复杂的公司，产品经理在处理需求的过程中都有可能需要写接口需求：例如：顺丰、金蝶、平安等等。
02
接口的自我介绍
大家好，我是你们已经认识很久的好朋友，我的名字叫“接口”。在平时的工作中，你们经常会讨论到我，并让我帮你解决很多问题。例如，前端的小姐姐需要查看用户“小明”的姓名、性别、身高、地址等用户信息时，她会将要求先告诉我，然后我会将前端小姐姐的要求转达给后端的小哥哥，待后端小哥哥按要求完成任务之后，我就会将前端姐姐想要的信息告诉她。
任务名称：用户信息查询
入参（查询条件）：用户姓名
出参（查询结果）：用户姓名、性别、身高、学历、地址、联系方式
汪童学
以上是“我”的自我介绍。是的，我就是这么牛逼PLUS。但是，我只能同时帮你们完成一件事情。当你们在完成数据写入的同时，需要刷新页面查询最新的数据时，我可以与我的兄弟姐妹联手满足你们的需求。
无论是在前端小姐姐与后端小哥哥之间，或是，在订单大哥与仓储大哥之间，我都可以利用我的能力帮你们解决很多问题，且你们只需要告诉我入参、出参、以及其他要求（例如：并发量、调用量、是否批量等）。下图是某公司官网开放平台的一个接口案例。
03
怎么写接口需求
仅从功能的角度去看产品，无论是C端产品还是B端产品，其实都是在为用户提供增、删、改、查、显服务，因此接口需求怎么写，我们可以分别从增、删、改、查、显的场景去思考。
① 查询
以顺丰的运费失效查询为例：客户在寄件前，需要预先运费时，可以通过在运费时效查询中输入原寄地、目的地，货物信息（重量、长、宽、高、件数）寄件时间 等信息，可以得出从深圳寄件到武汉的预估运费和预计时效。
上图是通过F12（浏览器检查工具），查看到的具体请求参数和返回参数。从请求参数中我们可以发现，用户使用运费时效查询工具时，在用户界面用户需要输入寄件地址的省市区和收件地址的省市区，但实际在执行查询动作的时候是将寄件省市区和收件省市区解析为区号，然后通过区号去查询并得到结果。由此我们可以倒推出，顺丰-运费时效查询的接口应该如下：
由上面模板可以得知，我们提供给开发的接口需求文档，主要需要描述以下内容：
应用场景：描述接口的应用场景
接口描述：描述接口的逻辑，例如运费单价查询逻辑，运费计算逻辑等
性能：接口的性能要求说明，包括调用量、并发量等，可以根据过去发生的业务量来评估；
调用方：接口的调用方
接口CODE：在旧接口中进行逻辑调整，需要把接口CODE附上；新开发的接口，接口CODE可以不写；
入参/出参：接口需求中最重要的组成部分之一，在查询的场景中，可以将入参理解为查询条件；出参理解为期望得到的查询结果；如接口需求支持批量查询，接口的出参需以list的形式返回，并需求说明数据分页规则
汪童学
② 新增
以顺丰的运单下单业务为例：当用户有寄件需求时，顺丰用户可以在顺丰官网、顺丰APP、顺丰公众号、顺丰小程序等多个渠道中任一渠道下单，但从实现层面来看，不同渠道的下单业务其实共用的一个下单接口。例如，用户去顺丰官网立即下单页面， 在寄件表单中分别填写寄方信息、收方信息、快件信息、快递产品等信息，用户填写完信息点击"立即下单"时调用下单接口完成下单。
在用户眼里，填写完寄件信息表单并点击立即下单，是完成了下单。从系统的角度去理解，实际是系统基于用户的行为新增了一条运单数据。
基于上面的用户界面截图可以知道，系统新增一笔运单，系统需要用户填写的寄方信息、收方信息、快件信息、快递产品等信息，由此可以倒推出顺丰新增运单的接口为：
③ 修改（更新）
修改（更新）场景的接口，与上面的新增接口类似，以用户修改账号密码的案例为例：用户在修改密码时，需要在表单中填写账号信息和密码信息，然后点击【确定】按钮，提交表单信息并更新账号信息。通过以上的描述，可以倒推出修改账号密码的接口应为：
④ 补充说明
上面分别从查询、新增、更新三个场景举例说明接口需求文档应该怎么写。需特别说明的是，一般情况下，仅当需求涉及跨业务系统的数据查询、新增、更新时，才需要产品经理去做需求调研并输出接口需求文档。
举个例子：
在查询的场景中，如仅仅只是查询本系统内容的数据，一般情况下不需要产品经理写接口需求文档。但如果在查询本系统的数据的同时，需要同时查其他系统的数据，这种场景就涉及到跨业务系统的数据查询，需在查询客户基础信息的同时联手另外一个接口完成信息查询。
例如：在查询客户数据的同时，需要查询对应客户在财务数据中的充值余额数据，此时就需要一个根据客户查询财务数据中对应个客户的充值余额数据的接口，来联合实现在查询客户基础数据的同时查询对应客户财务数据的功能需求，接口示例如下：
04
总结
对于接口：产品经理最好能有一定程度的理解，它可以帮助产品经理更深一层理解产品功能实现背后的事；虽然并不是所有的公司都会要求产品经理写接口需求，也并不是所有的需求过程中需求产品经理接口需求 ，但产品经理最好能理解并掌握如何处理接口需求。
在产品功能的实现的背后，后端服务与用户界面的交互、不同业务系统之间的交互都会用到API（接口）。以上这些内容是产品经理视角对产接口的理解。如从开发的角度去讨论接口，远不止这些。
