调用格式说明
收藏一、开发前须知
二、API 文档约定格式
服务端 API 文档格式主要如下：
${文档名} ${最后更新时间} ${接口介绍} ${注意事项} 请求 ${基本信息} ${请求头} ${路径参数} ${查询参数} ${请求体} ${请求体示例} ${注意事项} 响应 ${响应体} ${响应体示例} ${错误码} ${注意事项}
接口介绍
描述接口的作用。
注意事项
接口使用时需要注意的点。
请求
基本信息
介绍调用 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
{ "errno": 0, "message": "success", "data": { "session_key": "xxx", "openid": "xxx", "anonymous_openid": "xxx" } }
请求成功，没有返回 data
{ "errno": 0, "message": "success" }
请求失败
{ "errno": 40003, "message": "找不到相关第三方小程序应用" }
注意：
- •请求失败时可以根据 errno 的值到 API 文档里进行查阅，message 是错误的简要信息，请不要依据 message 来判定一个请求是否失败。
