公共请求内容

请求头:

  • 使用raw方式请传递application/json; charset=utf-8
  • 使用form方式请传递application/x-www-form-urlencoded
参数名 类型 是否必须 描述
Content-Type string 内容类型

公共参数:

  • 公共参数是指每个接口都需要使用到的请求参数,在接口文档中注释了「需要授权」则必须传,否则可以不传。
  • 文档中注释的「需要授权」并非绝对,而是根据框架默认设置的参数编写,您可以通过权限进行调整。
  • 在 API 模块配置文件中有一个api_debug参数,当值为true时表示是 API 调试模式,此时可以不传。
参数名 类型 是否必须 默认值 描述
appkey string 应用的 appkey,具体请参见管理组 API应用列表
token string 账号登录授权成功后,颁发给应用的授权信息,具体请参见 权限
sign string API 输入参数签名结果,签名算法请参见 签名
timestamp string 请求时间戳,时区 GMT+8,例如:1523553249 最大误差为 10 分钟。
format string json 响应格式。可选值:json,jsonp,xml
method string 业务方法,每个接口的业务方法都不同,具体请参考文档。

注意:不传入token值表示以游客的权限进行接口调用,接口如果支持则会返回数据。

format参数为jsonp时,默认处理方式返回jsonpReturn,如需自定义处理方式,需要额外添加callback参数,参数的值就是返回的处理方式。

参数method虽然属于公共参数,但建议包含在 HTTP Body 体中,与业务参数一起请求,这样业务逻辑会清楚很多。

业务参数

  • API 调用除了必须包含公共参数外,如果 API 本身有业务级的参数也必须传入,每个 API 的业务级参数请考文档说明。

公共返回

  • 客户端发送的每次调用请求,无论成功与否,系统都会返回数据。

json示例

  1. {
  2. "status": 200,
  3. "message": "success",
  4. "data": {}
  5. }

jsonp示例

  1. jsonpReturn({"status":200,"message":"success","data":{}});

xml示例

  1. <?xml version="1.0" encoding="utf-8"?>
  2. <careyshop>
  3. <status>200</status>
  4. <message>success</message>
  5. <data></data>
  6. </careyshop>
  • status状态码,200 表示成功,其他表示失败。
  • message消息信息,成功返回success,失败将提示失败原因。
  • data响应的数据,只有在请求成功时会存在该字段。

注意事项

  • 所有的请求和响应数据编码皆为utf-8格式,URL 里的所有参数名和参数值请做 URL 编码。
    • 如果是application/x-www-form-urlencoded,则 HTTP Body 体里的所有参数值也做 URL 编码;
    • 如果是application/json; charset=utf-8,则无需编码,但charset部分需要指定为utf-8
  • 参数名与参数值拼装起来的 URL 长度小于1024个字符时,可以用GET发起请求,否则必须使用POST
  • 部分接口在请求时对format参数设置了值也不会生效,这类接口通常是「异步请求」或「功能接口」,比如第三方支付的异步或二维码的生成,这类接口的返回格式由框架决定。
文档更新时间: 2018-09-11 14:41