什么是接口

因为最近在和快递100以及高德地图进行对接，所以最近在帮助研发的同学梳理接口文档内容。联想起踩过的的坑，觉得还是有必要去让产品的小伙伴去认识一下接口以及接口文档。

在互联网的研发过程中，一旦涉及到数据交互，包括前后端数据交互，往往都离不开接口调用。了解接口文档以及接口在产品经理的工作中扮演着非常重要的角色。懂得拆解接口设计要求，能够进一步帮助产品经历了去评估功能或模块开发的优先级，对开发排期也有着更深的理解。

image.png

图为百度对于API，即应用程序编程接口的一个解释，，本质就是一个已经定义好的方法或者函数逻辑，有点像软件测试中引入的黑盒概念，使用者无需知道这个方法是如何实现的，只需要按指定结构或者格式将数据传入黑盒，黑盒另一头就能输出我们想要的结果。

接口的用处

刚才也提到了，接口的主要用途就是接收某些特定的请求，并返回对应的结果，从而实现某个具体功能。比如一个接口的函数逻辑是平方计算，我们只需要传入数字3进来，拿着返回的数字9去处理别的问题，而不要在意接口是3+3+3得到的还是3*3得到的。

企业无需自己花时间和精力投入在具有较高技术壁垒或时间成本的需求上，简单地说就是“就算自己做也不一定做的好的活”就交给专业的人来做。
产品经理必懂的接口那些事儿 - 图2
eg：公司要开发一款理财APP，用户在注册时候必须经过人脸验证，对于公司，开发一套人脸识别程序成本较高，技术可复用的机会极少，自主研发投入产出比较低；于是公司去找商汤，旷世，寻找高效稳定的解决方案，购买平台，技术接口，这样既完成功能需求，也降低了项目成本。

API接口文档

接口文档的作用就是详细展示接口的使用方法的文档，一般由前后端的研发共同确定和定义，一份规范的接口文档是前后端开发工程师和平相处的前提。补充一句，不管是什么类型的文档，在一定程度上都是方便项目维护和迭代，避免人员流动导致信息断流。

接口文档的框架

image.png
接口文档一般分为七个部分：

  • 接口说明：即接口描述，包含接口的介绍，适用场景，使用说明和使用限制等相关规则。

image.png

  • 接口地址，接口正式的URL地址，需求方通过调用url，获取响应内容。

  • 请求方法，一般来说，最常见的是请求方法是GET和POST两种方法，即读接口和写接口，实现对数据的增删改（POST）查(GET)

    注意，GET请求提交的数据显示在地址栏里，不安全且数据量有限制，慎用。Post请求采用隐式提交，安全且没有数量限制，推荐

  • 请求参数，请求该接口时需要提供的参数，常见的参数属性：字段名称，字段，字段类型，是否必填，示例值，说明等。

  • 返回参数，接口正常响应后，返回的字段名称和规则等

    不管是请求还是返回参数，一般都分为5列：字段，说明，类型，备注，是否必填。

  • 服务器状态码或错误代码：接口请求失败后或者异常的时候，返回错误的代码，对应的释义以及排查方法等，这里和产品的异常处理非常相关，比如：

1.只会返回接口调用的成果与否
2.返回某些参数
3.返回列表

  • 实例，实际调用时响应的内容示例

高德地图API

接口设计

当产品经理产出详细的产品方案时，可以通过参与接口设计，详细地梳理、拆解设计细节：在梳理需求对应的接口时，先将功能细化，按照所设计的操作一步步拆解需求，想象每一步操作之后，前后端的交互以及后端逻辑分别是怎样的，然后再思考：

  • 用哪一种接口比较好；
  • 请求参数中应设置哪些字段、是否必填、有无字段格式要求等 -> 页面展示字段；
  • 返回参数中应设置哪些字段、是否必填、有无字段格式要求等 -> 页面提示或跳转；
  • 可能遇到哪些非理想情况、对应前端如何提示用户等 -> 提示文案；

举一个身边最常见的场景：
用户登录：用户输入登录信息后，后台根据所填手机号或用户名、密码等校验用户是否存在，如果存在，登录密码是否正确等，最终返回登录结果。

我们可以考虑到：
1）这一步虽然只涉及查询，不涉及写入操作，但考虑到安全性 -> 采用POST接口；
2）需要输入哪些信息? -> 请求参数字段有哪些，手机号、userID？
是否都必填？有无格式要求？-> 输入后前端校验规则：手机号必填，需为字符串，且长度有限制；
3）返回的登录结果 -> 返回参数字段有哪些？
4）非理想情况，例如网络不好 -> 对应前端提示文案，如 “不好! 网络崩溃啦”；

另外，PM 参与接口设计时，也可以站在需求或产品设计的角度，提供关于接口“扩展性”、“性能”、“稳定性” 等相关的建议：

  • 扩展性：新开发的接口将来能否用于其他功能？能否将现有的订单查询接口复用于新增页面的订单查询功能？
  • 性能：接口响应时间要保持在*s内；
  • 稳定性：支持多大量级的秒/分钟并发。

注：
1. 并发数：指同时访问服务器站点的连接数。如果需求方对此有严格要求，最好在上线前做好压力测试，验证接口能支持的最大并发数到底是多少。
2. 接口响应时间：指从请求端发送一个请求开始，到接收到响应结果所经历的时间，响应时间越短，多线程并发数越高，接口性能越好。