通用接口说明

目的

为了规范各个接口之间的共性内容，向前端开发者介绍接口用法，特设定该文档。API 接口只提供纯数据输出或者写行为，不包括样式或者模板呈现。接口不限定特定的客户端或服务端，使得 Android/iOS 客户端/HTML5/WindowPhone 和后台 WebService 数据操作均可适用，但某些情况下，会根据客户端提供 UserAgent（简单说，UserAgent 是客户端标识，说明“来者何人”，是什么的客户端） 进行适配。总的来说调用接口遵循以下原则。

• HTTP 协议通信和 JSON 数据格式，其响应 ContentType 为“application/json”
• URL 面向资源设计，即采用 HTTP RESTful 之风格
• 字符使用 UTF-8 编码

其中，JSON(JavaScript Object Notation) 是一种轻量级的数据交换格式，易于人阅读和编写，同时也易于机器解析和生成。它基于JavaScript Programming Language, Standard ECMA-262 3rd Edition - December 1999 的一个子集。JSON 提出者是 Douglas Crockford。RESTful 之风格，含状态传输（英文：Representational State Transfer，简称 REST），采用客户端/服务器模式，建立在分布式体系上，通过互联网通信，具有高延时（high latency）、高并发等特点。RESTful 架构是目前最流行的一种互联网软件架构。它结构清晰、符合标准、易于理解、扩展方便，所以正得到越来越多网站的采用。

所谓接口，直观来说是呈现如下截图的 JSON 数据。

顺手的调试工具是成功开发的一半，下面请让我们了解一下调试工具如何。

调试工具

虽然 curl 命令行工具就可以请求远端服务器，但推荐使用更直观的 GUI 工具，如 Firefox 下的插件，如下所示。

JSON结果查看插件：JSONView、JSON-handle如插图所示。

HTTP 请求发送工具：Poster，如插图所示。

HttpRequester，如插图所示。

路由规划

过去的 API 规划中，单笔新闻的 URL 比较常见的是使用问号加参数的形式，如 /news/?id=1000。但这里建议的写法则是 /news/1000。在 RESTful 语境中，一切都被认为是一种资源。而每个资源皆由 URL 标识。其命名方式总是以“http://主机名:端口+/二级目录（或可省略）+/实体（一般以英文单数形式）+其他操作的形式来拼装最终的 URL，例如 http://localhost:8080/myproject/news，其中 news 为读取新闻列表的接口。我们忽略 URL 前缀，简单说明接口的用法：

• GET /news             // 请求新闻列表，返回一笔或多笔新闻，或 null
• GET /news/1000   // 返回 id 为 1000 的新闻纪录，单个新闻的完整信息

尽管取消了如 ?id=XXX 的写法，但是“问号加参数的形式”依然得到保留。为了满足复杂的查询要求，列表操作还支持分页参数，以及传入多种条件和排序参数进行查询（如下所示）。

• GET /news/?start=0&limit=5              // 读取实体列表，指定分页参数 start=0&limit=5
• GET /news/?catalog=company_news // 读取实体列表，指定参数为 catalog=company_news，返回所有不分页；
• GET /news/?catalog=company_news&start=0&limit=3  // 读取实体列表，指定参数为 catalog=company_news，分页
• GET /news/…… ……                // 更多的查询手段。

上面只是针对实体对象。与关系型数据库中的“关系”类似，我们架构中存在着一种“关联对象”，例如新闻文章的配图 img，属于关联对象性质（关于结果输出的一点提示：如上所述，尽管实体对象和关联对象在路由规划层面有明确的划分，但 API 最终输出中不是强制分开的。有时出于减少 HTTP 请求的考虑，或者对象之间关联性较强，则可以将被关联对象合并到同一个接口中输出），于是我们可以通过这样的形式访问：

• GET /news/img    // 读取实体下面所有的关联对象的列表，凡是 img 属于 news 的，都会列出
• GET /news/img/11  // 返回 id 为 11 的新闻图片，显示该图片的详细信息
• GET /news//img?size=small // 支持复杂查询，这点不管对于实体对象还是关联对象皆是适用的。

关联对象并不具备单独接口，所以不存在如 /news/img 的接口。于是，创建、修改关联对象时候，分别是 POST news/img（创建），/news/img/10002（修改、删除）。
上述我们着重讨论获取信息行为，也就是 GET、读的操作。至于写的操作（创建、修改），会与前面提到的接口重叠，但 HTTP 方法和提交的内容不同。于是我们看到 URL 仍是 /news，但 HTTP  方法将是：

• PUT    /news            // 创建新的新闻
• POST  /news/1001  // 修改 id 为 1001 的新闻

提交内容每种业务对象都不相同——这不属于本文档讨论范围。关于各种请求方法，参见下一小节。

CRUD API

上述我们着重讨论获取信息行为，也就是 GET、读的操作。至于写的操作（创建、修改），会与前面提到的接口重叠，但 HTTP 方法和提交的内容不同。于是我们看到 URL 仍是 /news，但 HTTP 方法将是：

• PUT    /news            // 创建新的新闻
• POST  /news/1001  // 修改 id 为 1001 的新闻

RESTful 语境中 HTTP 方法即是对资源操作的谓词，分别是 GET/POST/PUT/DELETE 涵盖了各种读写操作，它们具体说明如表格所示。

HTTP方法	对应 CRUD 操作	读行为/写行为
GET        /uri/xxx	查看 Read，获取列表或单个实体	只读行为
POST      /uri/xxx	改 Update，修改实体内容	写行为
PUT        /uri	增 Create，新建一个实体	写行为
DELETE /uri/xxx	删 Delete，删除某条记录	写行为

CRUD 即“增、删、改、查”，也是与后端数据库一一对应。

创建操作可以使用 POST，也可以使用 PUT，区别在于 POST 是作用在一个集合资源之上的（/uri），而 PUT 操作是作用在一个具体资源之上的（/uri/xxx），再通俗点说，如果 URL 可以在客户端确定，那么就使用 PUT，如果是在服务端确定，那么就使用 POST，比如说很多资源使用数据库自增主键作为标识信息，而创建的资源的标识信息到底是什么只能由服务端提供，这个时候就必须使用 POST。

本文档所讨论的是基础模块。不同的业务对象，有不同的表和 SQL，也有不同的 Service，但接口层应该尽可能复用，如上述的复杂查询，无论实体对象还是关联对象都可用——即是一例。但某些子对象不能复用 SQL，要为其特别地写，如 /user/updatePassword。

 

 

通用接口操作

 

采用 RESTful 风格，基于 HTTP v1.1 协议，Content-type 为 application/json 的交互格式。字符使用 UTF-8 编码。下面以“新闻 news”为例子说明接口的交互，其他类型的实体相类似。

HTTP 方法	路径	操作	必填参数
GET	/news/list/show.do	请求新闻列表	start=0&limit=5, 指定分页参数
GET	/news/{id}/info.do	请求某条新闻详细内容（获取单个实体）	{id} 是 id 参数
DELETE	/news/{id}/delete.do	删除某条新闻记录（删除单个实体）	{id} 是 id 参数
POST	/news/create.do	创建一条新闻记录
PUT	/news/{id}/update.do	修改某条新闻记录	{id} 是 id 参数

注意事项：

• 参数可以是 QueryString 或 PathParam。
• 为了满足复杂的查询要求，某些接口“问号加参数的形式”依然得到保留。

API 接口说明

首先，应该定义一常量，说明 api 服务器的前缀，与下面各路径构成字符串，表示完整的接口 url。

1、获取单个实体 GET /{entity}/{id}/info.do参数是在 PathParam 的 id。没有数据返回：

{
    "isOk" : true,
    "result" : {}
}

有数据返回：

{

    "isOk": true,
    "result": {
          "updateDate": "2016-11-22T22:07:13.000Z",
          "forceUpdate": true,
          "version": 2016001,
          "downloadUrl": "http://localhost:8080/gdzbt/down_app/2016001.apk",
          "id": 1,
          "content": null,
          "uid": "19debdfe-66b8-4237-94ef-4e2ed5f313eb",
          "createDate": "2016-11-22T22:07:13.000Z",
          "cover": null,
          "name": "正式版"
    }
}

以上 JSON 结构含义如下：

字段名称及类型	含义
isOk:boolean	是否操作成功，true 表示成功
result:object	记录实体，使用 map 结构，空对象 {} 表示为没有数据

注意事项

• json 中 map/hash/字典/对象/keyvalue 皆可用 {} 表示。
• 日期格式如"2016-11-22T22:07:13.000Z",这是 UTC 国际协调时间。Java 转换方法

2、获取列表 GET /{entity}/list/show.do?start=0&limit=10请求参数

参数名称及类型	含义
start:int	分页起始数
limit:int	读取多少笔记录

响应结果没有数据返回：

{
    "msg" : "ok",
    "total" : 0,
    "result" : null
}

有数据返回：

{
    "msg" : "ok",
    "total" : 10,
    "result" : [
          {
                 "updateDate": "2016-11-22T22:07:13.000Z",
                 "forceUpdate": true,
                 "version": 2016001,
                 "downloadUrl": "/down_app/2016001.apk",
                 "id": 1,
                 "content": null,
                 "uid": "19debdfe-66b8-4237-94ef-4e2ed5f313eb",
                 "createDate": "2016-11-22T22:07:13.000Z",
                 "cover": null,
                 "name": "正式版"
         },
          {
                 "updateDate": "2016-11-22T22:07:13.000Z",
                 "forceUpdate": true,
                 "version": 2016002,
                 "downloadUrl": "/down_app/2016001.apk",
                 "id": 2,
                 "content": null,
                 "uid": "19debdfe-66b8-4237-94ef-4e2ed5f313eb",
                 "createDate": "2016-11-22T22:07:13.000Z",
                 "cover": null,
                 "name": "正式版2"
         }
       ]
}

以上 JSON 结构含义如下：

字段名称及类型	含义
msg:string	信息，ok 表示成功
total:int	记录总数，可用于分页计算用， 0 表示为没有数据
result:array	记录集合，为记录实体构成的数组。实体使用 map 结构。null 表示为没有数据

3、创建单个实体 POST /{entity}/create.do请求参数无请求参数

响应结果创建失败返回：

{
    "isOk" : false,
    "msg" : "创建失败！原因：XXXX"
}

创建成功返回：

{
    "isOk" : true,
    "msg" : "创建成功",
    "newlyId" : 1
}

以上 JSON 结构含义如下：

字段名称及类型	含义
isOk:boolean	true=成功/false=失败
msg:string	具体信息
newlyId:long	创建新实体返回 id，一般是自增 id

4、修改单个实体 PUT /{entity}/{id}/update.do请求参数为 PathParam 参数，表示实体 id。

响应结果修改失败返回：

{
    "isOk" : false,
    "msg" : "修改失败！原因：XXXX"
}

修改成功返回：

{
    "isOk" : true,
    "msg" : "修改成功"
}

以上 JSON 结构含义如下：

字段名称及类型	含义
isOk:boolean	true=成功/false=失败
msg:string	具体信息