产品经理不仅要有敏锐的市场洞察力，作为一个项目内部或外部的桥梁和翻译官，必须得懂些技术语言及实现原理，以便更好地与开发团队沟通，推动产品的技术实现和项目顺利落地。

本文帮助产品经理理解如何通过API实现跨平台服务的集成，提升产品的竞争力。撰写清晰、准确的API文档，确保开发团队和第三方开发者能够高效地对接。

产品经理遇到的困惑场景：

场景1：这个功能实现做不了，我们没有数据源，需要第三方的接口才好实现。😑
场景2：这个功能太复杂，设计接口就要20多个，工作量有点大，哪里来的工作量？
场景3：开发中没有对接口文档做全覆盖的设计，如异常等情况进行处理，漏点太多，被人笑话瞎设计

1、什么是API?

到底什么是API接口呢？接口文档又怎么看呢？

API，全称为应用程序编程接口（Application Programming Interface），是一套预先定义的函数、协议和工具，用于构建软件和应用程序。API作为软件组件之间通信的桥梁，允许不同的程序或服务之间进行交互，而无需了解或处理底层的源代码。

简单讲就是一套规则，它让一个软件程序能够向另一个软件程序传输数据。

API 让开发人员能够避免重复工作，根据 API 的要求设置请求格式来将现有功能纳入新的应用程序，而不是构建和重建现有应用程序功能。

网上其他的解释很难理解？我们用生活化场景举个例子

想象一下，当你走进一家餐厅吃饭，你就是用户，这家餐厅就是「软件应用程序」。

当你想点菜的时候，并不是直接告诉“厨师”，而是通过“服务员”转达你的需求；而“厨师”相当于“后台”，厨师接到订单后才会料理菜品，并由服务员将菜品传递给你。

你不需要会炒菜、也不必与厨师沟通，只要通过服务员就能够如愿享有期待的菜品，而服务员承担的正是“API”的角色。

2、如何看懂API文档？

大概原理了解后，那我们用实例来了解下API文档怎么看？以下是天气预报查询的API接口

通常API请求核心结构有四部分：API服务地址(请求地址/方法)、请求参数、返回结果参数说明、请求示例

<天气预报查询>

接口介绍

天气查询是一个简单的 HTTP 接口，根据用户输入的 adcode，查询目标区域当前/未来的天气情况，数据来源是中国气象局。

使用场景

需要使用相关天气查询的时候。

使用限制

服务调用量的限制一天≤24次。

API服务地址


请求地址URL	请求方式
https://restapi.amap.com/v3/weather/weatherInfo?parameters	GET
> parameters 代表的参数包括必填参数和可选参数。所有参数均使用和号字符(&)进行分隔。下面的列表枚举了这些参数及其使用规则。查询参数 (GET)：从具体的 API 说明文档中获取；查询参数前面需要携带问号（?），格式为 “参数名=参数取值”，参数之间用 “&” 相连。例如，`?limit=5` 表示查询不超过 5 条数据。


请求方法	说明
GET	请求服务器返回指定资源。
POST	请求服务器新增资源或执行特殊操作。
PUT	请求服务器全局更新指定资源。
PATCH	请求服务器局部更新指定资源。
DELETE	请求服务器删除指定资源。

请求参数

在请求地址中带入的参数，必填也就必传项；例如?extensions=base 表示返回实时天气。


参数名	含义	规则说明	是否必须	缺省值
key	请求服务权限标识	标识用户唯一性	必填	无
city	城市编码	输入城市的 adcode，例如”110101”=北京市东城区 adcode 信息可参考城市编码表	必填	无
extensions	气象类型	可选值：base/all base:返回实况天气 all:返回预报天气	可选	base
output	返回格式	可选值：JSON,XML	可选	JSON

返回结果参数说明

实况天气每小时更新多次，预报天气每天更新3次，分别在8、11、18点左右更新。由于天气数据的特殊性以及数据更新的持续性，无法确定精确的更新时间，请以接口返回数据的 reporttime 字段为准。


名称			含义	规则说明
status			返回状态	值为0或1 1：成功；0：失败
count			返回结果总数目
info			返回的状态信息
infocode			返回状态说明,10000代表正确
lives			实况天气数据信息
	province		省份名
	city	城市名
	adcode	区域编码
	weather	天气现象（汉字描述）
	temperature	实时气温	单位：摄氏度
	winddirection	风向描述
	windpower	风力级别	单位：级
	humidity	空气湿度
	reporttime	数据发布的时间	年月日时分秒
forecast			预报天气信息数据
	city		城市名称
	adcode	城市编码
	province	省份名称
	reporttime	预报发布时间
	casts	预报数据 list 结构，元素 cast,按顺序为当天、第二天、第三天的预报数据
		date	日期
		week	星期几
		dayweather	白天天气现象
		nightweather	晚上天气现象
		daytemp	白天温度
		nighttemp	晚上温度
		daywind	白天风向
		nightwind	晚上风向
		daypower	白天风力
		nightpower	晚上风力

请求示例

https://restapi.amap.com/v3/weather/weatherInfo?city=110101&extensions=base&key=

解释：查询110101=北京市东城区的实时天气数据，下方为返回的结果信息(JSON格式)

{
    "status" :"1",
    "count" :"1",
    "info" :"OK",
    "infocode" :"10000",
    "lives" :
        [
        "0" :
            {
                "province" :"北京",
                "city" :"东城区",
                "adcode" :"110101",
                "weather" :"多云",
                "temperature" :"4",
                "winddirection" :"西北",
                "windpower" :"6",
                "humidity" :"28",
                "reporttime" :"2024-11-27 21:02:41",
                "temperature_float" :"4.0",
                "humidity_float" :"28.0"
            }
        ]
}

上述就是常见的接口文档形式了，思考下，在设计时你会怎么设计界面？交互？提示？注意点？

当status=0；失败时，界面要提示用户吧？如：无法获取实时天气请稍后再试
正常时，考虑要怎么布局展示天气，纯文字吗？显然放上对应天气的图标更形象好理解
上述返回结果里面是否穷尽了各种天气对应天气图标？要将天气对应的图标设计全
调用是有次数限制的，如果超了如何提示用户？直接报异常显然太粗鲁了不友好
难免会碰到行政区域会有合并之类的，这时城市code发生变化做好用户提示没？
如果这个服务商的接口服务器挂了，无法提供查询，是否有提示用户？是否有告警到开发侧补救？
还有接口的一些性能、并发量的考量等等

以上关于API接口知识，还需要真实的结合到实际的工作当中，才能设计出好的产品，听到这里知道怎么设计了没？开发的工作量心里有底了没？提醒你的专业了没？

产品经理该懂的技术（API接口）