跳到主要内容
版本:3.4.4

接口约定

调用方式

本交互接口统一采用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
}

身份验证和会话

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

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

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