产品经理的 API 文档阅读指南

1、什么是 API？

API，全称 Application Programming Interface，即应用程序编程接口，我们日常中习惯简称为“接口”。API 在内部预先定义了函数，能够使开发人员无须明白 API 内部实现机制，就能够实现功能。

2、理解 API

要理解 API，需要明白两组关键词。

​第一组：封装和暴露。API 在内部封装了复杂的函数，暴露给外部的只是一个接口地址。开发人员在调用 API 实现功能时，只需按照既定的规则进行请求即可，而无需去理解该功能的实现逻辑。这一机制，使开发人员间的协作变得简洁、高效。

第二组：输入和返回。API 的本质是根据调用者输入的内容返回一些内容。

3、API 文档结构

API 文档内通常包括多个 API 的信息，单个 API 的信息通常包括以下内容：

接口描述、接口地址、请求方法、请求参数、响应内容、错误代码。

产品经理需要关注的信息包括接口描述、请求参数、响应内容、错误代码。

接口描述：该接口实现的功能说明。

请求参数：请求该接口时，需要提供的参数。参数属性包括名称、类型、是否必填、能否更新、描述等。

响应内容：接口正常响应后，返回的内容。

错误代码：接口请求失败后，返回的错误代码。

我们以一个简单的例子来做一个解析。微信的“输入微信号查找用户”功能中，输入的微信号就是“请求参数”，查看到的用户的昵称、头像就是“响应内容”，找不到该用户的提示就是“错误代码”。

4、熟悉 API 文档的好处

开发量把握：功能都是要依托 API 来实现的。但是由于功能和程序的区别，以及产品和开发对新旧的理解不同，所以会造成这样一种现象：新的功能不一定需要新的 API，相似的功能可能需要新添 API。

举个例子：游戏内的充值功能，实现了通过选择金额来充值。如果该接口中，金额对应的请求参数是枚举类，并不是将选择的金额处理成数值的话，在添加新功能“自定义充值金额”时，产品会将其视为同一个功能的优化，而在开发开来，这就是一个需要修改 API 的新功能。

产品经理在熟悉 API 文档后，就不会单纯地以产品的视角来定义功能的新旧，而是会综合 API 的修改程度来定义功能的新旧。这样的话，在对开发量的把握上能够更加准确。

产品抽象：在接受一个已有项目或依托官方 API 开发第三方平台时，对 API 文档的熟悉，能够大大提升产品抽象的能力。究其实质，所有的功能都是要依托 API 来实现的。查看已有产品，原型，需求文档等内容，只是从浅层次去做了解。而一旦对 API 文档熟悉，知道每个功能对应的 API 以后，你就可以透过表象，像搭积木一样使用 API 来构建功能。

5、实操案例

之前我负责一个第三方广告投放平台的产品。在刚接手项目时，我熟悉产品的方式是不断地在官方平台就行各种操作，熟悉所有的细节和流程。通过这样的方式完成产品结构图、用例流程图，然后来制作产品原型。这样的方式存在这样几个问题：

1）、模仿痕迹太重。官方平台是国外的设计风格，在易用性、体验上都和国内主流有所不同。一味的模仿导致产品的可用性较差，不太符合主流用户的操作习惯。

2）、效率低下。很多功能本质上都是一样的，但因为入口不同，让我误认为是不同的功能从，从而在相同的内容上浪费了时间。如果直接阅读 API 文档，就不会出现这一问题。

3）、对功能的依存关系理解错误。有一个创建项目的流程，官方平台在创建 A 的同时也创建了 B。而在我们平台设计中，创建 A 和创建 B 是可分离的。这样的设计在与官方平台做数据交互时存在一定的问题。而后来查看 API 文档时，很清晰地知道创建 A 的请求参数里 B 是必填项，如果早知道这一点，就不会出这种问题。

经过第一版的设计后，吸取了一些经验。在第二版设计的时候，就能够脱离产品表层交互，透视到深层的功能实现和数据交互。在做功能设计时，设计能够更加自由。

6、结语

对于第三方平台的产品经理来说，熟悉官方 API 文档，尤为重要。它能够帮助你更加自由高效可行地设计产品，对开发量有更清晰的把握。熟悉 API 文档，能够避免许多坑，也能够帮助你更加高效地与开发人员沟通。总之，熟悉 API 文档，应该是一个产品经理的基本功。