目的
为了规范各个接口之间的共性内容,向前端开发者介绍接口用法,特设定该文档。API接口只提供纯数据输出或者写行为,不包括样式或者模板呈现。接口不限定特定的客户端或服务端,使得Android/iOS客户端/HTML5/WindowPhone和后台WebService数据操作均可适用,但某些情况下,会根据客户端提供UserAgent进行适配。总的来说调用接口遵循以下原则。
HTTP协议通信和JSON数据格式,其响应ContentType为“application/json”URL面向资源设计,即采用HTTPRESTful之风格字符使用UTF-8编码
其中,JSON(JavaScriptObjectNotatio是一种轻量级的数据交换格式,易于人阅读和编写,同时也易于机器解析和生成。它基于JavaScriptProgrammingLanguage,StandardECMA-2623rdEdition-December1999的一个子集。JSON提出者是DouglasCrockford。RESTful之风格,含状态传输,采用客户端/服务器模式,建立在分布式体系上,通过互联网通信,具有高延时、高并发等特点。RESTful架构是目前最流行的一种互联网软件架构。它结构清晰、符合标准、易于理解、扩展方便,所以正得到越来越多网站的采用。
所谓接口,直观来说是呈现如下截的JSON数据。
顺手的调试工具是成功开发的一半,下面请让我们了解一下调试工具如何。
调试工具
虽然curl命令行工具就可以请求远端服务器,但推荐使用更直观的GUI工具,如Firefox下的插件,如下所示。
JSON结果查看插件:JSONView、JSON-handle如插所示。
HTTP请求发送工具:Poster,如插所示。
HttpRequester,如插所示。
路由规划
GET/news//请求新闻列表,返回一笔或多笔新闻,或nullGET/news/1000//返回id为1000的新闻纪录,单个新闻的完整信息
尽管取消了如?id=XXX的写法,但是“问号加参数的形式”依然得到保留。为了满足复杂的查询要求,列表操作还支持分页参数,以及传入多种条件和排序参数进行查询。
GET/news/?start=0&limit=5//读取实体列表,指定分页参数start=0&limit=5GET/news/?catalog=company_news//读取实体列表,指定参数为catalog=company_news,返回所有不分页;GET/news/?catalog=company_news&start=0&limit=3//读取实体列表,指定参数为catalog=company_news,分页GET/news/…………//更多的查询手段。
上面只是针对实体对象。与关系型数据库中的“关系”类似,我们架构中存在着一种“关联对象”,例如新闻文章的配img,属于关联对象性质,于是我们可以通过这样的形式访问:
GET/news/img//读取实体下面所有的关联对象的列表,凡是img属于news的,都会列出GET/news/img/11//返回id为11的新闻片,显示该片的详细信息GET/news//img?size=small//支持复杂查询,这点不管对于实体对象还是关联对象皆是适用的。
关联对象并不具备单独接口,所以不存在如/news/img的接口。于是,创建、修改关联对象时候,分别是POSTnews/img,/news/img/1000上述我们着重讨论获取信息行为,也就是GET、读的操作。至于写的操作,会与前面提到的接口重叠,但HTTP方法和提交的内容不同。于是我们看到URL仍是/news,但HTTP方法将是:
PUT/news//创建新的新闻POST/news/1001//修改id为1001的新闻
提交内容每种业务对象都不相同——这不属于本文档讨论范围。关于各种请求方法,参见下一小节。
上述我们着重讨论获取信息行为,也就是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是作用在一个集合资源之上的,而PUT操作是作用在一个具体资源之上的,再通俗点说,如果URL可以在客户端确定,那么就使用PUT,如果是在服务端确定,那么就使用POST,比如说很多资源使用数据库自增主键作为标识信息,而创建的资源的标识信息到底是什么只能由服务端提供,这个时候就必须使用POST。
本文档所讨论的是基础模块。不同的业务对象,有不同的表和SQL,也有不同的Service,但接口层应该尽可能复用,如上述的复杂查询,无论实体对象还是关联对象都可用——即是一例。但某些子对象不能复用SQL,要为其特别地写,如/user/updatePassword。
通用接口操作
采用RESTful风格,基于HTTPv1协议,Content-type为application/json的交互格式。字符使用UTF-8编码。下面以“新闻news”为例子说明接口的交互,其他类型的实体相类似。
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。
获取单个实体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:1000Z',这是UTC国际协调时间。Java转换方法
获取列表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 表示为没有数据 |
创建单个实体POST/{entity}/creatdo请求参数无请求参数
响应结果创建失败返回:
{
'isOk' : false,
'msg' : '创建失败!原因:XXXX'
}
创建成功返回:
{
'isOk' : true,
'msg' : '创建成功',
'newlyId' : 1
}
以上JSON结构含义如下:
isOk:boolean | true=成功/false=失败 |
msg:string | 具体信息 |
newlyId:long | 创建新实体返回 id,一般是自增 id |
修改单个实体PUT/{entity}/{id}/updatdo请求参数为PathParam参数,表示实体id。
响应结果修改失败返回:
{
'isOk' : false,
'msg' : '修改失败!原因:XXXX'
}
修改成功返回:
{
'isOk' : true,
'msg' : '修改成功'
}
以上JSON结构含义如下:
isOk:boolean | true=成功/false=失败 |
msg:string | 具体信息 |
文章为作者独立观点,不代表股票交易接口观点