4个要点,编写一份接口需求文档

54 评论 60543 浏览 687 收藏 11 分钟

在产品设计工作中,或多或少都会需要用到接口,特别是业务导向性的系统,接口几乎是必不可少的功能。那么什么是接口?如何写一份能准确表达业务需求的接口需求文档呢?

一、什么是接口

百科上对接口的定义:API(Application Programming Interface,应用程序编程接口)是一些预先定义的函数,目的是提供应用程序与开发人员基于某软件或硬件得以访问一组例程的能力,而又无需访问源码,或理解内部工作机制的细节。

要理解接口是什么,首先理解一下为什么要用接口?

两个独立的系统,它们的数据或程序是独立的,这就使得它们无法直接访问对方的数据库或程序(两个独立的数据相当于两个独立的家庭,每个家庭肯定是不允许外人随便进入的,否则会发生偷窃等后果严重的事件)。但是某些业务场景下,独立的系统之间又必须相互共享数据或共用一套程序逻辑,如统一业务流程上的不同业务操作系统,下游系统的业务依赖于上游系统的数据。

既然如此为什么不把它们设计成一个系统,这样不就没有上面的问题了吗?

这是因为有的业务流程很长很复杂,如果设计成一个系统,整个系统变得很庞杂,不论是功能设计、开发维护都很难。因此一般都会把虽然有上下游业务关系但又有清晰边界的业务划分成独立的系统实现,如采购系统和仓储系统。此外,很多时候我们需要获取的数据是我们外部其他公司拥有的数据,更不可能设计成同一个系统了。

基于以上两点:接口就是两个独立系统之间同步数据或访问对方程序的途径。

二、如何设计接口

1. 搞清楚是主动访问还是被动请求:

a. 若是主动访问,有两种情况:

一是我方是数据的使用方,需要主动从对方获取数据;二是我方是数据的提供方,需要主动将数据同步给对方。

主动访问时无需做接口,而是访问对方的接口,要搞清楚的问题是:我们需要在什么节点访问对方的接口?是用户触发某个操作的时候实时去访问?还是没有实时性要求,只是周期性地访问?

若我方是数据的使用方且需要的数据是用户使用某个功能必须的数据,因此必须在用户操作时实时去访问对方的接口获取数据并展示给用户,典型的有我们注册某网站时获取验证码的功能。

若我方是数据的使用方且需要的数据是一些跟用户实时操作无关的基础数据,如客服系统需要从其他业务系统获取用户的基础数据,以在系统中的某些功能下展示用户的信息(如客服在处理客诉等问题时,需要知道客户的一些详细信息,这些信息只有业务系统有)。这种情况下,一般会新增一个脚本定时(如两小时一次)访问对方的接口将数据获取过来存储到自己的数据库,在用到的时候直接从自己数据库获取并展示。

若我方是数据的提供方且提供的数据是下游系统需要的实时要求高的数据则更多地用实时同步;若是基础数据,则选择周期性同步的方式。

b. 若是被动请求,有两种情况:

一是我方是数据提供方,需要对方来获取数据;二是我方是数据使用方,需要对方主动将数据同步过来。

被动请求需要提供接口供对方访问,此时要搞清楚:让对方来访问的时候,需要提供什么样的参数?根据他提供的参数我们需要返回什么数据?这些数据从哪里取值?

若有一些数据的来源是本系统,其他系统需要使用这些数据,则可提供接口让其他系统通过访问接口获取这些数据。

若我方是数据使用方且让对方将数据主动同步过来,此种场景典型如——我们是业务的下游,上游系统产生数据后,需要将数据同步到下游系统让流程继续进行,并且流程的及时性要求高,不能有延迟。这种情况下,只有上游系统知道什么节点产生了数据,因此只有等他产生数据后主动推送给下游系统,因为下游系统因无法知道数据生成的时间,也就无法及时去获取数据,这时最好的方式是让对方主动将数据同步过来。

2. 搞清楚数据交互的实时性要求

a. 对于我方是数据使用方的情况,要根据业务的需要决定获取数据的实时性。

如上文所说,如果是用户使用功能时需要的数据就是即时性访问。如果是定期获取基础数据,根据我们对数据准确性的要求和对方数据变更的频率决定获取的周期。如我们对数据的准确性要求不是100%的要求,且对方的数据变更频率也不是很高,则周期可设计得长一些,如每天一次,每几个小时一次等。

b. 对于我方是数据提供方的情况,则以对方的业务需要为准,但是对于获取数据的访问量大等特殊情况,应在需求中或评审中做好说明和交代,以帮助开发设计更满足需要的接口。

3. 选择合适的接口方式

结合接口的不同类型和实时性要求两方面,可以选择合适的接口实现方式:

a. mq消息队列

是一个中间件,数据提供方将数据放到中间件,数据获取方从中间件中获取数据。针对向多个系统同步基础数据的需要,消息队列是最适合的方式。

若选择这种同步方式,要注意的一点是:增量同步还是全量同步,若是增量同步,对方是增量获取还是全量获取?若是全量同步,在什么情况下,对方应该更新数据,什么情况下应该更新数据?

b. otter同步

数据同步方直接访问数据获取方的数据表将数据写入对应的表中,这种方式实时性最高,若对数据的准确性要求很高,此方式是很好的数据同步方式。

c. http

一般在功能设计中常用的接口是此种方式,双方通过http地址保持数据同步和通信。

在设计具体的数据同步接口时,具体的方式产品经理不用关注,由开发根据需求设计合理的方式,然后产品可帮助开发一起确定所选方式是否满足业务需要。除非业务上有特殊要求,则在需求中可指定具体的方式。

三、如何编写接口文档

不同的接口使用场景,需要关注的点和交代清楚的规则不一样,以主动/被动+数据使用方/数据获取方的维度,有以下四种情况:

1. 如果是向对方系统主动推送数据,则可按以下方式整理接口需求

2. 如果是对方主动来获取数据,则可按以下方式整理接口需求

3. 如果是被动接收对方推送的数据,则可按以下方式整理接口需求

4. 如果主动从对方获取数据,则可按以下方式整理接口需求

PS:在下一篇文章中将以具体的文档实例来说明不同的场景应该考虑和注意的点。书写过程中一些偏技术的点应及时与开发咨询和沟通,防止编写的文档与实际出入太大;接口的开发肯定涉及两个系统,因此在评审前与对方产品对好文档是必须的,要保证双方开发拿到的文档标准是一样的,否则在开发过程中会出现双方约定不一致导致需要修改的情况。

#专栏作家#

果果,人人都是产品经理专栏作家。擅长业务导向性的产品设计,以及对业务流程的梳理和复杂问题的拆解,希望能找到产品工作的操作指南和方法论,不断搭建自己的知识体系

本文原创发布于人人都是产品经理。未经许可,禁止转载

题图来自Unsplash, 基于CC0协议

更多精彩内容,请关注人人都是产品经理微信公众号或下载App
评论
评论请登录
  1. 能在里面加一下示例就更棒了。谢谢

    来自江苏 回复
  2. 返回参数是不是只是系统记录一下,不会在页面展示吧

    来自上海 回复
    1. 这个看实际的业务需要,有一些信息是关键的业务信息,肯定是要解析转化后展示在界面上的

      来自广东 回复
  3. 明白这是给开发的需求文档,另外想问 对外的专业接口文档 也是产品来写吗?有没有什么标准的参考模板?thx

    来自广东 回复
    1. 对外的专业文档还是由开发来写比较好,因为里面要包含实例的;你可以到阿里或腾讯的开放平台看看,上面有很多开放的API接口文档,对外专业的就是那种的

      来自广东 回复
  4. JSON实例怎么写呢,比如JSON列表这种怎么表达报文???

    来自四川 回复
    1. 这种就让开发写,产品不写这个 哈哈哈

      来自广东 回复
    2. 我在迭代的时候会写。列个表格,包括字段、字段属性和定义,着重说明想去掉哪些字段增加哪些字段和原因就行。
      需求期间就着重写场景,当输入什么时返回什么也要列表说清。
      接手以前的老接口与主干接口时,需要明白用了哪些接口标准与协议,在对应接口使用处标明,需要有接口本身介绍,错误编码和示例。
      但我问了其他产品朋友,有些都不需要写接口需求,大概每种产品经理都不一样吧。

      来自四川 回复
  5. 谢谢麻雀,写的很好!

    来自四川 回复
    1. 谢谢肯定~~

      来自广东 回复
  6. 您好,想请教下:
    1.这个表格对于简单的接口会比较容易写,但是对于里面多个json格式的要怎么写呢?
    2.一般在写对外的接口文档中,我们经常要列【序号、字段英文名、字段中文名、是否必填、类型】等;您提供的表格是不是用于产品经理向开发提需求的时候用的,而不是开发对外提供的接口文档?
    3.感觉【字段来源】、【逻辑验证规则】提供了新思路,谢谢分享~

    来自广东 回复
    1. 是的 我这个只是产品给开发的接口需求描述文档,不是向外介绍接口的专业接口文档

      json格式的我理解应该是有主信息和明细信息区分,可以再分一列来交代是主信息,包含哪些明细

      专业开放接口的文档还是要参考一些开放平台上的说明,除了文档外要加上实例,你可以参考腾讯云、阿里云这些开放平台上的接口看看

      来自广东 回复
    2. 好的,谢谢~

      来自广东 回复
  7. 您好,请问向对方系统推送数据时,是对方系统调用我方接口吗?;被动接收对方推送的数据时,是我方调用对方接口吗?

    来自北京 回复
    1. 向对方系统推送数据时:是咱们访问对方的接口,将数据推给他
      被动接收对方推送的数据时:是对方访问咱们的接口把数据推过来
      你刚好理解反了 🙂

      来自广东 回复
    2. 现在明白了,谁主动谁就去调谁的接口 💡

      来自北京 回复
    3. 谁被动谁给接口

      来自四川 回复
    4. 是的

      来自北京 回复
  8. 增量同步还是全量同步,若是增量同步,对方是增量获取还是全量获取?若是全量同步,在什么情况下,对方应该更新数据,什么情况下应该更新数据?
    ————————————–
    增量同步和全量同步是不是贴重复了,可以再解释一下吗,不太懂这两个的区别,以及产品经理要明确什么,想学习一下,谢啦

    回复
    1. 增量的意思就是:持续同步新产生的数据,即每次只同步截止上次同步产生的新数据
      全量的意思就是:每次都把所有的数据都同步过去,不管是否已经同步过了

      来自广东 回复
    2. 增量接收的意思就是:对方每次接收到数据后按新数据对待,将接收的数据插入到数据库中
      全量接收的意思就是:对方每次接收到数据后全量更新之前的数据(以一定的唯一维度更新),若已有数据中没有的时候才插入新数据

      来自广东 回复
    3. 这一块产品只需要作为一个考量因素,具体方案可以在出方案的时候跟技术一起商讨确定;主要还是看业务上的情况 以及数据的量等因素共同确定

      来自广东 回复
  9. 老实说。最后一张表没看懂。

    来自上海 回复
    1. 就是你通过传参数的方式从对方接口获取你想要的数据;比如传输你的姓名,对方给你返回你的姓名、身份证号、手机号等等

      来自广东 回复
    2. 标题行管的到返回参数列码?比如“传输给对方的请求参数”、“状态”等,也属于“字段名称”吗?还有表2其实也有这个问题。

      来自上海 回复
    3. 也算呀 请求参数就是一个个字段的 自然就有字段名称嘛 状态本身就是个字段

      来自广东 回复
    4. 没想到你竟然回复了。

      来自上海 回复
  10. 感谢分享

    来自北京 回复
  11. 🐴

    回复
  12. 下周和合作方对接!我好激动!接口文档产品要写吗?需求里应该咋写

    回复
    1. 写需求文档就行了 按上面的模板写应该可以 但也要看你们的具体要求

      来自广东 回复
  13. 学习了!!期待下一篇的文档实例!

    回复
  14. m

    回复
  15. 学习了!接口需求没具体写过

    回复
  16. 赞,期待下一篇 🙂

    来自北京 回复
  17. 写得好呀。接口文档可能存在的坑太多了。字段的数据源/幂等处理/不同场景下主键的选择。还有最重要的,在面多多个合作方时,如何说服对方使用自己的标准API。

    来自上海 回复
  18. 写的很好,接口需求在需求文档里我从来没写过,领教了,希望多写一些这样的文章

    来自上海 回复
  19. 高手啊

    来自河北 回复
    1. 1

      来自广东 回复
    2. 谢谢~

      来自广东 回复
  20. 接口文档一般不是开发写吗?

    回复
    1. 这是需求文档哦

      回复
  21. 您好 请问文章可以转载吗???

    来自广东 回复
    1. 要转载到哪里呢?

      回复
  22. 感觉这应该是IT方案需要知道的基本知识,产品只需要知道业务场景需要哪些数据,然后具体实现由SE制定方案

    来自广东 回复
    1. 是的 产品就是要交代清楚哪些节点要跟哪个系统进行什么样的交互 具体交互方式由研发定

      回复
  23. MQ中丢了,同步增量还是全量

    回复
    1. 嗯嗯 是的 增量同步还是全量同步 以及增量消费还是全量消费 都要定义好 不然容易出bug

      回复
  24. 下一篇什么时候出呢

    来自江苏 回复
    1. 还不一定哈 工作太忙就比较少时间写 有问题可以先交流😄

      回复
    2. 谢谢~

      来自广东 回复
    3. 多谢关注哦,还不一定啥时候写完 ➡

      来自广东 回复
  25. 产品经理如果熟悉架构师的工作,的确增加不少竞争力。

    回复
    1. 😬还有很多东西要学习 现在还只是浅层的认识

      回复