新增加的apis.tianapi.com接口域名解决了自2015年至今遗留的一些问题,例如风格不统一的请求地址,语义不恰当的数组名等。老域名api.tianapi.com继续正常维护到2024年底,两年之后再根据实际情况逐步调整。如果您当前请求接口用的是老域名,建议在下次项目迭代时更换到apis.tianapi.com新域名,并根据最新接口文档略调返回的公共参数(主要为newslist[]数组调整为result{}对象)。
早期平台内所有接口返回的JSON数据都是封装在newslist这个特殊数组中。对于非新闻资讯类接口,特别是只有单个数据集的接口,不够形象也容易误解,本次优化对新域名下的JSON数据结构也进行了调整,非多行数据直接包含在result对象中。
新老域名多个结果集时返回的JSON结构(社会新闻API)对比,点击图片放大查看:
新老域名单个结果集时返回的JSON结构(天行机器人API)对比:
新域名当接口返回的数据是单个数据集时可以直接result[key]方式调用,多个数据集时会嵌套在result对象下的list数组中。
新域名多数据集时返回的数据结构:
{ "code": 200, "msg": "success", "result": { "list": [ { "id": "0decc4d9b8cde282", "ctime": "2015-07-17", "title": "那个抱走王明涵的,你上微信吗?看完这个你会心软吗?", "description": "中国传统文化", "type": "学霸族" } ] } }
新域名单数据集时返回的数据结构:
{ "code": 200, "msg": "success", "result": { "reply": "亲爱的主公你好,我叫小天!", "datatype": "text" } }
接口文档示例已全部更新为新域名下的数据结构,老域名和新域名除了公共参数部分结构不同,其他应用参数基本一致。
以PHP代码举例,新域名的调用方式:
社会新闻API等多行数据接口典型结构,将原来的遍历数组$data['newslist']替换成$data['result']['newslist']:
$data = json_decode($tianapi_data,true); //将json解析成php变量 foreach($data['result']['newslist'] as $list) { //遍历数组数据集,新域名列表在result对象下的newslist或list数组中 echo $list['title']; //输出新闻标题 }
天行机器人等单行数据接口典型结构,将原来的$data['newslist'][0]['reply']替换成$data['result']['reply']:
$data = json_decode($tianapi_data,true); //将json解析成php变量 echo $data['result']['reply']; //输出机器人回复,新域名单行数据集直接包含在result对象中
新旧域名的主要差异如下表:
旧域名api.tianapi.com | 新域名apis.tianapi.com | |
---|---|---|
接口返回的JSON数据结构 | 结果全部包含在newslist[]数组中,例如:{"newslist":[{"title":"标题"}]} | 结果全部包含在result{}对象中,例如:{"result":{"title":"标题"}},多行结果则嵌套在result对象下的list[]数组中 |
是否支持2023年后上线的新接口 | 不支持 | 支持 |
接口如果有新增应用参数(字段) | 不增加 | 增加 |
维护周期 | 2024.12.31前(正常维护) 2025.01.01后(逐步停止维护) | 永久 |
其他提示,以快递接口为例:
旧域名的接口URI有以下三种形式,均可访问:
1,https://api.tianapi.com/kuaidi/ 2,https://api.tianapi.com/txapi/kuaidi/index 3,https://api.tianapi.com/kuaidi/index
新域名的全部接口统一为以下URI形式:
1,https://apis.tianapi.com/kuaidi/index
新老域名只有返回数据的json结构公共参数部分略有调整,其他如IP地址等均无任何变化。