公共请求

请求头

  • 使用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参数设置了值也不会生效，这类接口通常是「异步请求」或「功能接口」，比如第三方支付的异步或二维码的生成，这类接口的返回格式由框架决定。