API接口文档

前面讲到的关于接口的请求方式、类型、原理、安全机制等，产品经理能够简单了解一些就可以满足日常工作中的需要。接口文档是产品经理日常工作中经常会使用到的，特别是做开放平台或B端的产品经理，需要经常的看和写接口文档。

那如何看接口文档呢？首先，看接口文档的场景一般是自身业务模块需要获取外部的数据，但又不想自己重新开发，寻找外部已经实现的有开放能力的供应商（包含企业内部的）。比如淘宝开放平台、微信开放平台等等，需要获取淘宝订单或者使用微信支付，不需要自己开发对应的工具，可以调用对方的开放接口。

接口文档一般包含三个部分，即接口说明（签名获取方法、访问频率和并发、错误码）、接口参数（包括请求参数和返回参数）以及接口代码示例。

其次，是要明确自身的业务需求，需要通过外部接口获取什么能力，具体到需要什么参数。去供应商的开放平台找到对应的接口，查看接口返回参数是否有你想要的信息，注意一些用户个人信息参数都是加密的，还需要通过解密接口获取。

最后，如果在接口满足你诉求的之后，再去看开放平台需要获取这些接口的要求是什么，以及接口开放的权限范围，看下自己是否满足这些要求。如果不去看的话，可能会白白浪费很多调研时间。

写接口文档，接口文档的查看对象一般是研发和测试人员，所以大致内容就包括接口的使用场景、接口请求方式、错误码、接口说明等几个部分。其中接口说明分为请求参数和返回参数，请求参数包含：英文字段、字段类型、示例值、是否必填、字段说明。返回参数包含：英文字段、字段类型、示例值、字段说明。如下图：

1. 参数说明

   • 通用参数说明

     • version:API版本
     • key:调用key,测试key:test_api_key
     • api_name:API类型[item_get,item_search]
     • cache:[yes,no]默认yes，将调用缓存的数据，速度比较快
     • result_type:[json,xml,serialize,var_export]返回数据格式，默认为json
     • lang:[cn,en,ru] 翻译语言，默认cn简体中文

   • API:item_get 参数说明: num_iid:宝贝ID

 

1688.item_get

公共参数

名称	类型	必须	描述
key	String	是	调用key（必须以GET方式拼接在URL中）
secret	String	是	调用密钥
api_name	String	是	API接口名称（包括在请求地址中）[item_search,item_get,item_search_shop等]
cache	String	否	[yes,no]默认yes，将调用缓存的数据，速度比较快
result_type	String	否	[json,jsonu,xml,serialize,var_export]返回数据格式，默认为json，jsonu输出的内容中文可以直接阅读
lang	String	否	[cn,en,ru]翻译语言，默认cn简体中文
version	String	否	API版本

请求参数

请求参数：num_iid=610947572360

参数说明：num_iid:1688商品ID
sales_data:&sales_data=1 获取近30天成交数据
agent:&agent=1 获取1688分销代发价格数据

响应参数

Version: Date:

名称	类型	必须	示例值	描述
item	item[]	0		宝贝详情数据