跳到主要内容
版本：4.0.0

HTTP 接口约定

调用方式​

本交互接口统一采用HTTP JSON调用方式，提交实体和返回实体均为UTF-8编码的JSON数据。

不同接口规定了不同的调用方式，有些采用GET调用方式，有些采用POST调用方式，有的采用PUT，有的采用DELETE。当接口采用GET调用方式时，调用者通过URI中直接指定各个参数，被调用方返回JSON格式应答数据。当接口采用POST或PUT调用方式时，调用者以约定的JSON格式作为HTTP实体内容调用指定的URL，被调用方返回JSON格式应答数据。

一般地，调用方式有以下语义：

  • GET: 查询
  • POST: 新增
  • PUT: 修改
  • DELETE: 删除

API地址和路径​

为了区分接口版本，在接口端点(End point)的路径上设置了一个版本号，目前本版的所有接口都在/v1/路径下，即接口的端点为：

https://<host>:<port>/v1/

为了简化书写，本章的请求方法表示中均不包含/v1/路径前缀，在实际调用需要此前缀。例如登录接口的请求方法一栏为 POST /login。例如测试服务器运行在n11.gratour.info:7011，则本版本（v1）的实际请求URL为：

https://n11.gratour.info:7011/v1/login

查询接口的约定​

查询接口一般采用GET HTTP方法。

__limit/__page分页参数​

当接口支持时，可通过__limit/__page两个参数来实现分页。 其中：

  • __limit：要求返回的记录数（分页时），最大2000。当不要求或不支持分页时，不指定此参数。
  • __page: 要求的页码（分页时），1为第一页。当不要求或不支持分页时，不指定此参数。

查询结果​

查询接口返回的JSON对象中的data数组属性包含了查询结果数据，而count属性则指明整个查询的总记录数（对于分页查询，这个总记录数不一定是本次分页查询结果的记录数）。如果没有任何记录，count属性为0，data数组为空，但该data属性保留在json对象中。

新增/修改接口的约定​

  • 新增记录接口一般采用POST HTTP方法，修改记录接口一般采用PUT HTTP方法。
  • 调用者按照格式将数据组织成JSON格式，并将JSON数据作为HTTP体提交请求。
  • 一般地，如果一个字段它的值为NULL，则在JSON数据中不应出现该字段。例如下列对象中的description字段（属性）为NULL，则不应该编码为：
{
  "name": "Tom",
  "description": "description"
}

而应如下省略此属性，如下：

{
  "name": "Tom"
}

JSON数据的数据类型​

JSON数据中的字段采用如下格式：

  • 日期，以字符串表示，格式为：yyyy-MM-dd。
  • 时间戳，JSON数据中的时间戳字段以字符串表示，格式为：yyyy-MM-dd HH:mm:ss。部分接口中时间戳以长整形(long)表示，值为epoch milli-seconds。
  • 布尔数据类型，JSON数据中标明为布尔数据值一律按标准表示(true/false)，不可使用0/1代替。

应答的约定​

调用者在等到HTTP响应后，应首先检查响应的HTTP状态码。本接口正常应答的HTTP状态码为200，但部分错误使用特定的HTTP状态码，详情参见特定错误和HTTP状态码。

一般地，应答都包括errCode，message。errCode错误码属性标志服务对所请求操作的执行情况，具体错误码定义参见《错误码定义》。message属性为错误信息，由服务直接给出错误消息文本。注意：错误消息文本仅用于调试用途，一般展现给用户的消息文本应由调用者进行本地化。

如果接口有返回数据，则有count属性和data属性。其中count属性指明整个查询结果的记录数（非分页结果的记录数）。data属性为数组，为数据结果；根据接口的不同，数组元素有不同的类型。

当发生错误时，可没有count和data属性。应用应首先检查错误码，一般地，如果错误码不为0，则不需要再进一步检查data属性。

示例1（更新型接口的无返回数据应答）：

{
  "errCode": 0,
  "message": "OK"
}

示例2（查询型接口的有返回数据应答）：

{
  "errCode": 0,
  "message": "OK",
  "data": [
    {
      "id": 12423423,
      "comId": "035104",
      "userId": "U0001",
      "updateTime": "2019-08-01 10:00:05"
    }
  ],
  "count": 1
}

特定错误和HTTP状态码​

发生以下错误时，API服务会将响应(Response)的HTTP状态码设置为特定的状态码：

错误HTTP状态码设置为
访问未授权的URL401 Unauthorized
用未定义的HTTP方法访问URL（如 PUT /alm）403 Forbidden
未提供X-Auth-Token403 Forbidden
无效的X-Auth-Token403 Forbidden
会话过期403 Forbidden
使用了不支持的HTTP方法（如 HEAD, PATCH等）404 Not found
不存在的URL404 Not found

身份验证和会话​

首先客户端使用用户名/密码调用登录 [ /login ]接口，服务端验证成功后返回一个会话令牌（sessionId, 随机字符串），然后客户端在后续的HTTP请求中带上这个令牌，以证实调用者的身份。登录获得令牌后，客户端发出请求时，可选择以下两种方式之一将令牌传给服务端：

  1. 在请求中添加X-Auth-Token请求头，令牌作为该头部的值
  2. 在请求参数中添加__token参数，令牌作为该参数的值

令牌具有生存期。每次客户端调用会延长令牌的生存期，在一段时间无活动后，令牌失效。无活动指服务端没有收到来自相同会话令牌的接口调用。