- 调用格式说明
- Postman模板使用说明
- 第三方小程序应用密钥使用说明
- 第三方小程序应用上传资源
- 第三方小程序应用上传资源V2
- 授权
- 域名
- 模板管理
- 代商家管理小程序
- 代商家入驻抖音开放平台
调用格式说明
更新时间 2024-07-24 02:58:49
收藏
我的收藏一、开发前须知
二、API 文档约定格式
服务端 API 文档格式主要如下:
text复制${文档名}
${最后更新时间}
${接口介绍}
${注意事项}
请求
${基本信息}
${请求头}
${路径参数}
${查询参数}
${请求体}
${请求体示例}
${注意事项}
响应
${响应体}
${响应体示例}
${错误码}
${注意事项}
接口介绍
描述接口的作用。
注意事项
接口使用时需要注意的点。
请求
基本信息
介绍调用 API 所需要的请求方式、路径和权限等信息。
- •HTTP URL:服务端 API 的 URL。
- •HTTP Method:服务端 API 仅支持 HTTPS 协议和标准 HTTP 方法,如 GET、POST 等。
- •权限要求:调用 API 所需要的权限。
请求参数
调用 API 的详细入参说明,参数使用风格遵循 RESTful,请注意不同参数在调用时的位置。
- •请求头:这部分参数需要放在 HTTP 请求的 Header 中,主要包含 HTTP
Content-Type
。- •路径参数:这部分参数需要放置在 URL 中,在文档中一般以
:
开头。- •查询参数:这部分参数需要在 URL 后使用
?
进行连接,多个查询参数间以 &
分隔。- •请求体:这部分参数需要放在 HTTP 请求的 Body 中,一般为
form-data
或 JSON
格式。- •请求体示例:对应 API 的成功请求参数的样例。
注意事项
传入入参时需要注意的点。
响应
调用 API 的返回值。
- •响应体:一次 API 调用后,HTTP 响应中 Body 部分的内容。
- •响应体示例:API 成功请求结果的样例。
- •错误码:调用该 API 可能返回的错误码解释以及排查建议。
注意事项
处理响应体时需要注意的点。
三、API 响应结果说明
绝大多数 API 的响应体结构包括 errno、message、data 三个部分。
errno 为错误码,message 为错误信息,data 为 API 的调用结果。默认请求成功时,errno 为 0,message 为 success。data 在一些操作类 API 的返回中可能不存在。
例如:
请求成功,并且返回 data
json复制{
"errno": 0,
"message": "success",
"data": {
"session_key": "xxx",
"openid": "xxx",
"anonymous_openid": "xxx"
}
}
请求成功,没有返回 data
json复制{
"errno": 0,
"message": "success"
}
请求失败
json复制{
"errno": 40003,
"message": "找不到相关第三方小程序应用"
}
注意:
- •请求失败时可以根据 errno 的值到 API 文档里进行查阅,message 是错误的简要信息,请不要依据 message 来判定一个请求是否失败。
点击纠错