APP推广合作
联系“鸟哥笔记小乔”
接口文档,产品经理怎么看?
2024-01-08 10:29:45

来源|Kevin改变世界的点滴

产品经理会调研各式各样的第三方需求能力。

以满足产品提供用户所需要的功能,比如第三方登录、图像识别、风控算法,都有专注的服务厂商。

通过接入第三方能力,企业无需自己花时间和精力投入在具有较高技术壁垒或时间成本的需求上。就算企业自己做,也做不好。

所以,产品经理学会看API接口文档,是一项产品经理的基本功,可以提升产品设计质量、以及和开发沟通效率。

那么,一个合格的接口文档包含什么内容?

接口文档,产品经理怎么看?

接口文档范围

有了接口文档,我们可以知道第三方能力的功能逻辑、功能的边界、和接入的条件。比如要接口当天的天气接口信息,可以查看下面的接口。

接口文档,产品经理怎么看?

比如万年历的接口文档描述了接口的传输数据是当天详情。

接口文档,产品经理怎么看?

▲ 万年历的能力描述

接口文档的编写规范

各个公司甚至一家公司的不同项目组,接口文档都可能不一样。项目成员的前后端开发工程师会去定义接口,并且随着需求变化,接口文档也需要不断维护。

所以经常有不懂接口文档的产品经理如果让开发同学你把后台功能给其他部门直接用、或者某某客户端你把你的app直接给某某部门后台用。

这个时候,“开发的拳头就捏紧了。”

在一家公司不同项目下,接口仍然有规范不一致的情况,更何况公司之间的数据交流。这也是为什么有产品经理的公司,都不会选择外包。外包开发意味着后期维护在接口、规范上都是不清楚的,难以搞清楚对方的撰写代码思路和潜在问题。

接口规范集中在4点维度上去做规范

1.接口方法

新增post

修改put

删除(delete)

获取(get)

通过上面4个定义接口的权限。

2.URI定义

以/a开头,如果你的账户涉及到需要登录权限、比如我们的微信开放平台、第三方单点登录,则需要/u。如果是通过后台要查询数据库列表,则以/search结尾。如果是查询前台的列表则以/list结婚

3.请求参数和返回参数

两个类型参数都分为5列:字段、说明、类型、备注、是否必填。

接口文档,产品经理怎么看?

▲ 接口的参数案例

字段:类的属性

说明:中文解释字段什么意思

类:属性类型

有string(字符串)、number(整数)、object(对象)、arrar(数组)四种类型。

备注:接口的能力或逻辑解释,或者可以写一下列子,有的情况有列子会让开发人员看得懂一些。比如json

返回参数:返回参数和产品经理的异常是非常相关的。比如

  1. 只会返回接口调用成功或失败

  2. 返回某些参数

  3. 返回列表

上面3种返回形式都包含内容有区别。

第一种

新增、删除、修改等,只需要一个结果即可。

第二种

结构体有2个,第一个是code/mesaeg/dat ,第二个是data里写返回的参数,data是object类型

第三种

过于偏向开发知识,就不再叙述。

接口文档主要有什么

互联网企业要开放能力给其公司或开发者使用,就需要创建接口和定制接口规范。
常见的产品形态有开放平台这类形式。通过开发者注册账户,创建单独秘钥,再提供接口允许开发者获取能力。
如下是喜马拉雅的开放平台下提供的音频能力的SDK、API接入文档。在接口文档里面有前面提到的规范内容。

接口文档,产品经理怎么看?

▲ 喜马拉雅接口文档

请求后会有响应。在代码层面会有如下的显示规则

serid Long 用户ID

usernick String 用户登录名

sessionkey String 用户会话key

示例

请求

“XXXX”

响应

{“usersession11”:

{“userid”:”12512313”,

“usernck”:” name1 “,

”sessionkey”:”2122323232332435353”,

}}

响应有结果,并且显示调用成功则表示接口调通。

开放平台文档字段说明

第一:请求

说明请求地址,告诉如何调用接口

第二:调用秘钥

比如喜马拉雅要求申请秘钥,走开放平台账户协议进行注册。

第三:API测试

接通后会显示什么结果,如何知道接口是否接通?就需要在接口文档里面知道成功的参数接口文档,产品经理怎么看?

▲ 请求测试

同理可以在微信开放平台上可以看到

接口文档,产品经理怎么看?

▲ 微信开放平台的接口文档描述

多个接口文档组成的接口目录让产品经理和开发者快速查询功能点,以集成到自己的产品中。所以产品经理做第三方能力调研,最多时间的就是去看对方的接口文档。

包括对接口的描述,比如下图是地理位置获取。可以看到在该接口下,可以看到地理位置获取失败、成果的提示。

接口文档,产品经理怎么看?

▲ 微信公众平台提供位置信息的接口

Kevin改变世界的点滴
分享到朋友圈
收藏
收藏
评分

综合评分:

我的评分
Xinstall 15天会员特权
Xinstall是专业的数据分析服务商,帮企业追踪渠道安装来源、裂变拉新统计、广告流量指导等,广泛应用于广告效果统计、APP地推与CPS/CPA归属统计等方面。
20羽毛
立即兑换
一书一课30天会员体验卡
领30天VIP会员,110+门职场大课,250+本精读好书免费学!助你提升职场力!
20羽毛
立即兑换
顺丰同城急送全国通用20元优惠券
顺丰同城急送是顺丰推出的平均1小时送全城的即时快送服务,专业安全,准时送达!
30羽毛
立即兑换
Kevin改变世界的点滴
Kevin改变世界的点滴
发表文章314
PMTalk产品经理社区发起人,《产品之光》作者。产品经理创业者的斜杠青年。
确认要消耗 羽毛购买
接口文档,产品经理怎么看?吗?
考虑一下
很遗憾,羽毛不足
我知道了

我们致力于提供一个高质量内容的交流平台。为落实国家互联网信息办公室“依法管网、依法办网、依法上网”的要求,为完善跟帖评论自律管理,为了保护用户创造的内容、维护开放、真实、专业的平台氛围,我们团队将依据本公约中的条款对注册用户和发布在本平台的内容进行管理。平台鼓励用户创作、发布优质内容,同时也将采取必要措施管理违法、侵权或有其他不良影响的网络信息。


一、根据《网络信息内容生态治理规定》《中华人民共和国未成年人保护法》等法律法规,对以下违法、不良信息或存在危害的行为进行处理。
1. 违反法律法规的信息,主要表现为:
    1)反对宪法所确定的基本原则;
    2)危害国家安全,泄露国家秘密,颠覆国家政权,破坏国家统一,损害国家荣誉和利益;
    3)侮辱、滥用英烈形象,歪曲、丑化、亵渎、否定英雄烈士事迹和精神,以侮辱、诽谤或者其他方式侵害英雄烈士的姓名、肖像、名誉、荣誉;
    4)宣扬恐怖主义、极端主义或者煽动实施恐怖活动、极端主义活动;
    5)煽动民族仇恨、民族歧视,破坏民族团结;
    6)破坏国家宗教政策,宣扬邪教和封建迷信;
    7)散布谣言,扰乱社会秩序,破坏社会稳定;
    8)宣扬淫秽、色情、赌博、暴力、凶杀、恐怖或者教唆犯罪;
    9)煽动非法集会、结社、游行、示威、聚众扰乱社会秩序;
    10)侮辱或者诽谤他人,侵害他人名誉、隐私和其他合法权益;
    11)通过网络以文字、图片、音视频等形式,对未成年人实施侮辱、诽谤、威胁或者恶意损害未成年人形象进行网络欺凌的;
    12)危害未成年人身心健康的;
    13)含有法律、行政法规禁止的其他内容;


2. 不友善:不尊重用户及其所贡献内容的信息或行为。主要表现为:
    1)轻蔑:贬低、轻视他人及其劳动成果;
    2)诽谤:捏造、散布虚假事实,损害他人名誉;
    3)嘲讽:以比喻、夸张、侮辱性的手法对他人或其行为进行揭露或描述,以此来激怒他人;
    4)挑衅:以不友好的方式激怒他人,意图使对方对自己的言论作出回应,蓄意制造事端;
    5)羞辱:贬低他人的能力、行为、生理或身份特征,让对方难堪;
    6)谩骂:以不文明的语言对他人进行负面评价;
    7)歧视:煽动人群歧视、地域歧视等,针对他人的民族、种族、宗教、性取向、性别、年龄、地域、生理特征等身份或者归类的攻击;
    8)威胁:许诺以不良的后果来迫使他人服从自己的意志;


3. 发布垃圾广告信息:以推广曝光为目的,发布影响用户体验、扰乱本网站秩序的内容,或进行相关行为。主要表现为:
    1)多次发布包含售卖产品、提供服务、宣传推广内容的垃圾广告。包括但不限于以下几种形式:
    2)单个帐号多次发布包含垃圾广告的内容;
    3)多个广告帐号互相配合发布、传播包含垃圾广告的内容;
    4)多次发布包含欺骗性外链的内容,如未注明的淘宝客链接、跳转网站等,诱骗用户点击链接
    5)发布大量包含推广链接、产品、品牌等内容获取搜索引擎中的不正当曝光;
    6)购买或出售帐号之间虚假地互动,发布干扰网站秩序的推广内容及相关交易。
    7)发布包含欺骗性的恶意营销内容,如通过伪造经历、冒充他人等方式进行恶意营销;
    8)使用特殊符号、图片等方式规避垃圾广告内容审核的广告内容。


4. 色情低俗信息,主要表现为:
    1)包含自己或他人性经验的细节描述或露骨的感受描述;
    2)涉及色情段子、两性笑话的低俗内容;
    3)配图、头图中包含庸俗或挑逗性图片的内容;
    4)带有性暗示、性挑逗等易使人产生性联想;
    5)展现血腥、惊悚、残忍等致人身心不适;
    6)炒作绯闻、丑闻、劣迹等;
    7)宣扬低俗、庸俗、媚俗内容。


5. 不实信息,主要表现为:
    1)可能存在事实性错误或者造谣等内容;
    2)存在事实夸大、伪造虚假经历等误导他人的内容;
    3)伪造身份、冒充他人,通过头像、用户名等个人信息暗示自己具有特定身份,或与特定机构或个人存在关联。


6. 传播封建迷信,主要表现为:
    1)找人算命、测字、占卜、解梦、化解厄运、使用迷信方式治病;
    2)求推荐算命看相大师;
    3)针对具体风水等问题进行求助或咨询;
    4)问自己或他人的八字、六爻、星盘、手相、面相、五行缺失,包括通过占卜方法问婚姻、前程、运势,东西宠物丢了能不能找回、取名改名等;


7. 文章标题党,主要表现为:
    1)以各种夸张、猎奇、不合常理的表现手法等行为来诱导用户;
    2)内容与标题之间存在严重不实或者原意扭曲;
    3)使用夸张标题,内容与标题严重不符的。


8.「饭圈」乱象行为,主要表现为:
    1)诱导未成年人应援集资、高额消费、投票打榜
    2)粉丝互撕谩骂、拉踩引战、造谣攻击、人肉搜索、侵犯隐私
    3)鼓动「饭圈」粉丝攀比炫富、奢靡享乐等行为
    4)以号召粉丝、雇用网络水军、「养号」形式刷量控评等行为
    5)通过「蹭热点」、制造话题等形式干扰舆论,影响传播秩序


9. 其他危害行为或内容,主要表现为:
    1)可能引发未成年人模仿不安全行为和违反社会公德行为、诱导未成年人不良嗜好影响未成年人身心健康的;
    2)不当评述自然灾害、重大事故等灾难的;
    3)美化、粉饰侵略战争行为的;
    4)法律、行政法规禁止,或可能对网络生态造成不良影响的其他内容。


二、违规处罚
本网站通过主动发现和接受用户举报两种方式收集违规行为信息。所有有意的降低内容质量、伤害平台氛围及欺凌未成年人或危害未成年人身心健康的行为都是不能容忍的。
当一个用户发布违规内容时,本网站将依据相关用户违规情节严重程度,对帐号进行禁言 1 天、7 天、15 天直至永久禁言或封停账号的处罚。当涉及欺凌未成年人、危害未成年人身心健康、通过作弊手段注册、使用帐号,或者滥用多个帐号发布违规内容时,本网站将加重处罚。


三、申诉
随着平台管理经验的不断丰富,本网站出于维护本网站氛围和秩序的目的,将不断完善本公约。
如果本网站用户对本网站基于本公约规定做出的处理有异议,可以通过「建议反馈」功能向本网站进行反馈。
(规则的最终解释权归属本网站所有)

我知道了
恭喜你~答对了
+5羽毛
下一次认真读哦
成功推荐给其他人
+ 10羽毛
评论成功且进入审核!审核通过后,您将获得10羽毛的奖励。分享本文章给好友阅读最高再得15羽毛~
(羽毛可至 "羽毛精选" 兑换礼品)
好友微信扫一扫
复制链接