通达信交易接口:通用接口说明

HttpRequester，如插所示。

PUT/通达信交易接口,news//创建新的新闻POST/通达信交易接口,news/1001//修改id为1001的新闻

响应结果创建失败返回：

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

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

以上JSON结构含义如下：

isOk:boolean	是否操作成功，true 表示成功
result:object	记录实体，使用 map 结构，空对象 {} 表示为没有数据

上面只是针对实体对象。与关系型数据库中的“关系”类似，我们架构中存在着一种“关联对象”，例如新闻文章的配img，属于关联对象性质，于是我们可以通过这样的形式访问：

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

{
    'isOk' : true,
    'result' : {}
}

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

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

采用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 参数

修改单个实体PUT/{entity}/{id}/updatdo请求参数为PathParam参数，表示实体id。

以上JSON结构含义如下：

isOk:boolean	true=成功/false=失败
msg:string	具体信息

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

调试工具

其中，JSON(JavaScriptObjectNotatio是一种轻量级的数据交换格式，易于人阅读和编写，同时也易于机器解析和生成。它基于JavaScriptProgrammingLanguage,StandardECMA-2623rdEdition-December1999的一个子集。JSON提出者是DouglasCrockford。RESTful之风格，含状态传输，采用客户端/服务器模式，建立在分布式体系上，通过互联网通信，具有高延时、高并发等特点。RESTful架构是目前最流行的一种互联网软件架构。它结构清晰、符合标准、易于理解、扩展方便，所以正得到越来越多网站的采用。

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

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

有数据返回：

{

    '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': '正式版'
    }
}

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

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

创建单个实体POST/{entity}/creatdo请求参数无请求参数

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

通用接口说明

路由规划

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/…………//更多的查询手段。

响应结果没有数据返回：

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

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

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

有数据返回：

{
    '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'
         }
       ]
}

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

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

通用接口操作

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

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

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

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

以上JSON结构含义如下：

isOk:boolean	true=成功/false=失败
msg:string	具体信息
newlyId:long	创建新实体返回 id，一般是自增 id

以上JSON结构含义如下：

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

注意事项

注意事项：

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

start:int	分页起始数
limit:int	读取多少笔记录

响应结果修改失败返回：

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

创建成功返回：

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

API接口说明

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

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

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

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

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

文章为作者独立观点，不代表股票交易接口观点