第三方平台
接口说明

如何调用服务端 API

最后更新于 2021-06-25

开发前须知

序号注意事项参考文档
1在调用服务端 API 前,确保已正确获取 API 所需的凭证授权流程
2查询名词解释,了解常用术语概念定义第三方平台概念
3查询服务端错误码表,了解排查建议详见各接口文档下方错误码部分

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-dataJSON 格式。
  • 请求体示例:对应 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 来判定一个请求是否失败。
  • 反馈问题时,为便于开发人员排查,希望能提供以下信息,包括但不限于第三方应用 appid、请求时间、请求地址、请求参数、logid(http response header 中 x-tt-logid 字段)、具体报错表现、可否复现等,越详细越好。
  • logid 获取方式:
点击纠错
评价此篇文档