后端开发者可以先看这个详细的 图文入门教程
请求：
{
"User":{
}
}
返回：
{
"User":{
"id":38710,
"sex":0,
"name":"TommyLemon",
"tag":"Android&Java",
"head":"http://static.oschina.net/uploads/user/1218/2437072_100.jpg?t=1461076033000",
"date":1485948110000,
"pictureList":[
"http://static.oschina.net/uploads/user/1218/2437072_100.jpg?t=1461076033000",
"http://common.cnblogs.com/images/icon_weibo_24.png"
]
},
"code":200,
"msg":"success"
}
请求：
{
"[]":{
"count":3, //只要3个
"User":{
"@column":"id,name" //只要id,name这两个字段
}
}
}
返回：
{
"[]":[
{
"User":{
"id":38710,
"name":"TommyLemon"
}
},
{
"User":{
"id":70793,
"name":"Strong"
}
},
{
"User":{
"id":82001,
"name":"Android"
}
}
],
"code":200,
"msg":"success"
}
请求：
{
"Moment":{
},
"User":{
"id@":"Moment/userId" //User.id = Moment.userId
}
}
返回：
{
"Moment":{
"id":12,
"userId":70793,
"date":"2017-02-08 16:06:11.0",
"content":"1111534034"
},
"User":{
"id":70793,
"sex":0,
"name":"Strong",
"tag":"djdj",
"head":"http://static.oschina.net/uploads/user/585/1170143_50.jpg?t=1390226446000",
"contactIdList":[
38710,
82002
],
"date":"2017-02-01 19:21:50.0"
},
"code":200,
"msg":"success"
}
请求：
{
"[]":{ //请求一个数组
"page":0, //数组条件
"count":2,
"Moment":{ //请求一个名为Moment的对象
"content$":"%a%" //对象条件，搜索content中包含a的动态
},
"User":{
"id@":"/Moment/userId", //User.id = Moment.userId 缺省引用赋值路径，从所处容器的父容器路径开始
"@column":"id,name,head" //指定返回字段
},
"Comment[]":{ //请求一个名为Comment的数组，并去除Comment包装
"count":2,
"Comment":{
"momentId@":"[]/Moment/id" //Comment.momentId = Moment.id 完整引用赋值路径
}
}
}
}
返回：
{
"[]":[
{
"Moment":{
"id":15,
"userId":70793,
"date":1486541171000,
"content":"APIJSON is a JSON Transmission Structure Protocol…",
"praiseUserIdList":[
82055,
82002,
82001
],
"pictureList":[
"http://static.oschina.net/uploads/user/1218/2437072_100.jpg?t=1461076033000",
"http://common.cnblogs.com/images/icon_weibo_24.png"
]
},
"User":{
"id":70793,
"name":"Strong",
"head":"http://static.oschina.net/uploads/user/585/1170143_50.jpg?t=1390226446000"
},
"Comment[]":[
{
"id":176,
"toId":166,
"userId":38710,
"momentId":15,
"date":1490444883000,
"content":"thank you"
},
{
"id":1490863469638,
"toId":0,
"userId":82002,
"momentId":15,
"date":1490863469000,
"content":"Just do it"
}
]
},
{
"Moment":{
"id":58,
"userId":90814,
"date":1485947671000,
"content":"This is a Content...-435",
"praiseUserIdList":[
38710,
82003,
82005,
93793,
82006,
82044,
82001
],
"pictureList":[
"http://static.oschina.net/uploads/img/201604/22172507_aMmH.jpg"
]
},
"User":{
"id":90814,
"name":7,
"head":"http://static.oschina.net/uploads/user/51/102723_50.jpg?t=1449212504000"
},
"Comment[]":[
{
"id":13,
"toId":0,
"userId":82005,
"momentId":58,
"date":1485948050000,
"content":"This is a Content...-13"
},
{
"id":77,
"toId":13,
"userId":93793,
"momentId":58,
"date":1485948050000,
"content":"This is a Content...-77"
}
]
}
],
"code":200,
"msg":"success"
}
| 开发流程 | 传统方式 | APIJSON |
|---|---|---|
| 接口传输 | 等后端编辑接口，然后更新文档，前端再按照文档编辑请求和解析代码 | 前端按照自己的需求编辑请求和解析代码。 没有接口，更不需要文档！前端再也不用和后端沟通接口或文档问题了！ |
| 兼容旧版 | 后端增加新接口，用v2表示第2版接口，然后更新文档 | 什么都不用做！ |
| 前端请求 | 传统方式 | APIJSON |
|---|---|---|
| 要求 | 前端按照文档在对应URL后面拼接键值对 | 前端按照自己的需求在固定URL后拼接JSON |
| URL | 不同的请求对应不同的URL，基本上有多少个不同的请求就得有多少个接口URL | 相同的操作方法(增删改查)都用同一个URL， 大部分请求都用7个通用接口URL的其中一个 |
| 键值对 | key=value | key:value |
| 结构 | 同一个URL内table_name只能有一个 base_url/get/table_name? key0=value0&key1=value1... |
同一个URL后TableName可传任意数量个 base_url/get/ { TableName0:{ key0:value0, key1:value1, ... }, TableName1:{ ... } ... } |
| 后端操作 | 传统方式 | APIJSON |
|---|---|---|
| 解析和返回 | 取出键值对，把键值对作为条件用预设的的方式去查询数据库，最后封装JSON并返回给前端 | 把Parser#parse方法的返回值返回给前端就行 |
| 返回JSON结构的设定方式 | 由后端设定，前端不能修改 | 由前端设定，后端不能修改 |
| 前端解析 | 传统方式 | APIJSON |
|---|---|---|
| 查看方式 | 查文档或问后端，或等请求成功后看日志 | 看请求就行，所求即所得，不用查、不用问、不用等。也可以等请求成功后看日志 |
| 解析方法 | 用JSON解析器来解析JSONObject | 可以用JSONResponse解析JSONObject，或使用传统方式 |
| 后端的返回结果 | 传统方式 | APIJSON |
|---|---|---|
| User | { "data":{ "id":38710, "name":"xxx", ... }, "code":200, "msg":"success" } |
{ "User":{ "id":38710, "name":"xxx", ... }, "code":200, "msg":"success" } |
| Moment和对应的User | 分别返回两次请求的结果，获取到Moment后取出userId作为User的id条件去查询User Moment: { "data":{ "id":235, "content":"xxx", ... }, "code":200, "msg":"success" } User: { "data":{ "id":38710, "name":"xxx", ... }, "code":200, "msg":"success" } |
一次性返回，没有传统方式导致的 长时间等待结果、两次结果间关联、线程多次切换 等问题 { "Moment":{ "id":235, "content":"xxx", ... }, "User":{ "id":38710, "name":"xxx", ... }, "code":200, "msg":"success" } |
| User列表 | { "data":[ { "id":38710, "name":"xxx", ... }, { "id":82001, ... }, ... ], "code":200, "msg":"success" } |
{ "User[]":[ { "id":38710, "name":"xxx", ... }, { "id":82001, ... }, ... ], "code":200, "msg":"success" } |
| Moment列表，每个Moment包括发布者User和前3条Comment | Moment里必须有 1.User对象 2.Comment数组 { "data":[ { "id":235, "content":"xxx", ..., "User":{ ... }, "Comment":[ ... ] }, { "id":301, "content":"xxx", ..., "User":{ ... }, ... }, ... ], "code":200, "msg":"success" } |
1.高灵活，可任意组合 2.低耦合，逻辑很清晰 { "[]":[ { "Moment":{ "id":235, "content":"xxx", ... }, "User":{ ... }, "Comment[]":[ ... ] }, { "Moment":{ "id":301, "content":"xxx", ... }, "User":{ ... }, ... }, ... ], "code":200, "msg":"success" } |
| User发布的Moment列表，每个Moment包括发布者User和前3条Comment | 1.大量重复User，浪费流量和服务器性能 2.优化很繁琐，需要后端扩展接口、写好文档，前端/前端再配合优化 { "data":[ { "id":235, "content":"xxx", ..., "User":{ "id":38710, "name":"Tommy" ... }, "Comment":[ ... ] ... }, { "id":470, "content":"xxx", ..., "User":{ "id":38710, "name":"Tommy" ... }, "Comment":[ ... ] ... }, { "id":511, "content":"xxx", ..., "User":{ "id":38710, "name":"Tommy" ... }, "Comment":[ ... ] ... }, { "id":595, "content":"xxx", ..., "User":{ "id":38710, "name":"Tommy" ... }, "Comment":[ ... ] ... }, ... ], "code":200, "msg":"success" } |
以上不同请求方式的结果: ① 常规请求 { "[]":[ { "Moment":{ "id":235, "content":"xxx", ... }, "User":{ "id":38710, "name":"Tommy" ... }, "Comment[]":[ ... ] }, ... ], "code":200, "msg":"success" } ② 省去重复的User { "User":{ "id":38710, "name":"Tommy", ... }, "[]":[ { "Moment":{ "id":235, "content":"xxx", ... }, "Comment[]":[ ... ] }, ... ], "code":200, "msg":"success" } ③ 不查询已获取到的User { "[]":[ { "Moment":{ "id":235, "content":"xxx", ... }, "Comment[]":[ ... ] }, ... ], "code":200, "msg":"success" } |
1.base_url指基地址，一般是顶级域名，其它分支url都是在base_url后扩展。如base_url:http://apijson.cn:8080/ ，对应的GET分支url:http://apijson.cn:8080/get/ 。下同。
2.请求中的key或value任意一个为null值时，这个 key:value键值对 被视为无效。下同。
3.请求中的 / 需要转义。JSONRequest.java已经用URLEncoder.encode转义，不需要再写；但如果是浏览器或Postman等直接输入url/request，需要把request中的所有 / 都改成 %252F 。下同。
4.code，指返回结果中的状态码，200表示成功，其它都是错误码，值全部都是HTTP标准状态码。下同。
5.msg，指返回结果中的状态信息，对成功结果或错误原因的详细说明。下同。
6.code和msg总是在返回结果的同一层级成对出现。对所有请求的返回结果都会在最外层有一对总结式code和msg。对非GET类型的请求，返回结果里面的每个JSONObject里都会有一对code和msg说明这个JSONObject的状态。下同。
7.id等字段对应的值仅供说明，不一定是数据库里存在的，请求里用的是真实存在的值。下同。
| 方法及说明 | URL | Request | Response |
|---|---|---|---|
| GET: 普通获取数据， 可用浏览器调试 |
base_url/get/ | { TableName:{ … } } {…}内为限制条件 例如获取一个id为235的Moment： { "Moment":{ "id":235 } } |
{ TableName:{ ... }, "code":200, "msg":"success" } 例如 { "Moment":{ "id":235, "userId":38710, "content":"APIJSON,let interfaces and documents go to hell !" }, "code":200, "msg":"success" } |
| HEAD: 普通获取数量， 可用浏览器调试 |
base_url/head/ | { TableName:{ … } } {…}内为限制条件 例如获取一个id为38710的User所发布的Moment总数： { "Moment":{ "userId":38710 } } |
{ TableName:{ "code":200, "msg":"success", "count":10 }, "code":200, "msg":"success" } 例如 { "Moment":{ "code":200, "msg":"success", "count":10 }, "code":200, "msg":"success" } |
| GETS: 安全/私密获取数据， 用于获取钱包等 对安全性要求高的数据 |
base_url/gets/ | 最外层加一个"tag":tag，其它同GET | 同GET |
| HEADS: 安全/私密获取数量， 用于获取银行卡数量等 对安全性要求高的数据总数 |
base_url/heads/ | 最外层加一个"tag":tag，其它同HEAD | 同HEAD |
| POST: 新增数据 |
base_url/post/ | { TableName:{ … }, "tag":tag } {…}中id由后端生成，不能传 例如一个id为38710的User发布一个新Moment： { "Moment":{ "userId":38710, "content":"APIJSON,let interfaces and documents go to hell !" }, "tag":"Moment" } |
{ TableName:{ "code":200, "msg":"success", "id":38710 }, "code":200, "msg":"success" } 例如 { "Moment":{ "code":200, "msg":"success", "id":120 }, "code":200, "msg":"success" } |
| PUT: 修改数据， 只修改所传的字段 |
base_url/put/ | { TableName:{ "id":id, … }, "tag":tag } {…}中id必传 例如修改id为235的Moment的content： { "Moment":{ "id":235, "content":"APIJSON,let interfaces and documents go to hell !" }, "tag":"Moment" } |
同POST |
| DELETE: 删除数据 |
base_url/delete/ | { TableName:{ "id":id }, "tag":tag } {…}中id必传，一般只传id 例如删除id为120的Moment： { "Moment":{ "id":120 }, "tag":"Moment" } |
同POST |
1.TableName指要查询的数据库表Table的名称字符串。第一个字符为大写字母，剩下的字符要符合英语字母、数字、下划线中的任何一种。对应的值的类型为JSONObject，结构是 {...}，里面放的是Table的字段(列名)。下同。
2."tag":tag 后面的tag是非GET、HEAD请求中匹配请求的JSON结构的key，一般是要查询的table的名称，由后端Request表中指定。下同。
3.GET、HEAD请求是开放请求，可任意组合任意嵌套。其它请求为受限制的安全/私密请求，对应的 方法、tag、结构 都必须和 后端Request表中所指定的 一一对应，否则请求将不被通过。下同。
4.GETS与GET、HEADS与HEAD分别为同一类型的操作方法，请求稍有不同但返回结果相同。下同。
5.在HTTP通信中，自动化接口(get,gets,head,heads,post,put,delete) 全用HTTP POST请求。下同。
6.所有JSONObject都视为容器(或者文件夹)，结构为 {...} ，里面可以放普通对象或子容器。下同。
7.每个对象都有一个唯一的路径(或者叫地址)，假设对象名为refKey，则用 key0/key1/.../refKey 表示。下同。
| 功能 | 键值对格式 | 使用示例 |
|---|---|---|
| 查询数组 | "key[]":{}，后面是JSONObject，key可省略。当key和里面的Table名相同时，Table会被提取出来，即 {Table:{Content}} 会被转化为 {Content} | {"User[]":{"User":{}}}，查询一个User数组。这里key和Table名都是User，User会被提取出来，即 {"User":{"id", ...}} 会被转化为 {"id", ...} |
| 匹配选项范围 | "key{}":[]，后面是JSONArray，作为key可取的值的选项 | "id{}":[38710,82001,70793]，对应SQL是id IN(38710,82001,70793)，查询id符合38710,82001,70793中任意一个的一个User数组 |
| 匹配条件范围 | "key{}":"条件0,条件1..."，条件为任意SQL比较表达式字符串，非Number类型必须用''包含条件的值，如'a' | "id{}":"<=80000,>90000"，对应SQL是id<=80000 OR id>90000，查询id符合id<=80000 | id>90000的一个User数组 |
| 包含选项范围 | "key<>":Object => "key<>":[Object]，key对应值的类型必须为JSONArray，Object类型不能为JSON | "contactIdList<>":38710，对应SQL是json_contains(contactIdList,38710)，查询contactIdList包含38710的一个User数组 |
| 判断是否存在 | "key}{@":{ "from":"Table", "Table":{ ... } } 其中： }{ 表示 EXISTS； key 用来标识是哪个判断； @ 后面是 子查询 对象，具体见下方 子查询 的说明。 |
"id}{@":{ "from":"Comment", "Comment":{ "momentId":15 } } WHERE EXISTS(SELECT * FROM Comment WHERE momentId=15) |
| 远程调用函数 | "key()":"函数表达式"，函数表达式为 function(key0,key1...)，会调用后端对应的函数 function(JSONObject request, String key0, String key1...)。 可使用 - 和 + 表示优先级，解析 key-() > 解析当前对象 > 解析 key() > 解析子对象 > 解析 key+() |
"isPraised()":"isContain(praiseUserIdList,userId)"，会调用 boolean isContain(JSONObject request, String array, String value) 函数，然后变为 "isPraised":true 这种（假设点赞用户id列表包含了userId，即这个User点了赞） |
| 引用赋值 | "key@":"key0/key1/.../refKey"，引用路径为用/分隔的字符串。以/开头的是缺省引用路径，从声明key所处容器的父容器路径开始；其它是完整引用路径，从最外层开始。 被引用的refKey必须在声明key的上面。如果对refKey的容器指定了返回字段，则被引用的refKey必须写在@column对应的值内，例如 "@column":"refKey,key1,..." |
"Moment":{ "userId":38710 }, "User":{ "id@":"/Moment/userId" } User内的id引用了与User同级的Moment内的userId， 即User.id = Moment.userId，请求完成后 "id@":"/Moment/userId" 会变成 "id":38710 |
| 子查询 | "key@":{ "range": "ALL", "from":"Table", "Table":{ ... } } 其中： range 可为 ALL,ANY； from 为目标表 Table 的名称； @ 后面的对象类似数组对象，可使用 count 和 join 等功能。 |
"id@":{ "from":"Comment", "Comment":{ "@column":"min(userId)" } } WHERE id=(SELECT min(userId) FROM Comment) |
| 模糊搜索 | "key$":"SQL搜索表达式" => "key$":["SQL搜索表达式"]，任意SQL搜索表达式字符串，如 %key%(包含key), key%(以key开始), %k%e%y%(包含字母k,e,y) 等，%表示任意字符 | "name$":"%m%"，对应SQL是name LIKE '%m%'，查询name包含"m"的一个User数组 |
| 正则匹配 | "key~":"正则表达式" => "key~":["正则表达式"]，任意正则表达式字符串，如 ^[0-9]+$ ，*~ 忽略大小写，可用于高级搜索 | "name~":"^[0-9]+$"，对应SQL是name REGEXP '^[0-9]+$'，查询name中字符全为数字的一个User数组 |
| 连续范围 | "key%":"start,end" => "key%":["start,end"]，其中 start 和 end 都只能为 Boolean, Number, String 中的一种，如 "2017-01-01,2019-01-01" ，["1,90000", "82001,100000"] ，可用于连续范围内的筛选 | "date%":"2017-10-01,2018-10-01"，对应SQL是date BETWEEN '2017-10-01' AND '2018-10-01'，查询在2017-10-01和2018-10-01期间注册的用户的一个User数组 |
| 新建别名 | "name:alias"，name映射为alias，用alias替代name。可用于 column,Table,SQL函数 等。只用于GET类型、HEAD类型的请求 | "@column":"toId:parentId"，对应SQL是toId AS parentId，将查询的字段toId变为parentId返回 |
| 增加 或 扩展 | "key+":Object，Object的类型由key指定，且类型为Number,String,JSONArray中的一种。如 82001,"apijson",["url0","url1"] 等。只用于PUT请求 | "praiseUserIdList+":[82001]，对应SQL是json_insert(praiseUserIdList,82001)，添加一个点赞用户id，即这个用户点了赞 |
| 减少 或 去除 | "key-":Object，与"key+"相反 | "balance-":100.00，对应SQL是balance = balance - 100.00，余额减少100.00，即花费了100元 |
| 逻辑运算 | &, |, ! 逻辑运算符 ① & 可用于"key&{}":"条件"等 ② | 可用于"key|{}":"条件", "key|{}":[]等，一般可省略 ③ ! 可单独使用，如"key!":Object，也可像&,|一样配合其他功能符使用 |
① "id&{}":">80000,<=90000"，对应SQL是id>80000 AND id<=90000，即id满足id>80000 & id<=90000② "id|{}":">90000,<=80000"，同"id{}":">90000,<=80000"，对应SQL是 id>80000 OR id<=90000，即id满足id>90000 | id<=80000③ "id!{}":[82001,38710]，对应SQL是 id NOT IN(82001,38710)，即id满足 ! (id=82001 | id=38710)，可过滤黑名单的消息 |
| 数组关键词，可自定义 | "key":Object，key为 "[]":{} 中{}内的关键词，Object的类型由key指定 ① "count":Integer，查询数量，0 表示最大值，默认最大值为100 ② "page":Integer，查询页码，从0开始，默认最大值为100，一般和count一起用 ③ "query":Integer，查询内容 0-对象，1-总数，2-以上全部 总数关键词为total，和query同级，通过引用赋值得到，如 "total@":"/[]/total" 这里query及total仅为GET类型的请求提供方便，一般可直接用HEAD类型的请求获取总数 ④ "join":"&/Table0/key0@,</Table1/key1@" 多表连接方式： "<" - LEFT JOIN ">" - RIGHT JOIN "&" - INNER JOIN "|" - FULL JOIN "!" - OUTTER JOIN "@" - APP JOIN 其中 @ APP JOIN 为应用层连表，会从已查出的主表里取得所有副表 key@ 关联的主表内的 refKey 作为一个数组 refKeys: [value0, value1...]，然后把原来副表 count 次查询 key=$refKey 的 SQL 用 key IN($refKeys) 的方式合并为一条 SQL 来优化性能； 其它 JOIN 都是 SQL JOIN，具体功能和 MySQL,PostgreSQL 等数据库的 JOIN 一一对应， "ViceTable":{ "key@:".../MainTable/refKey" } 会对应生成 MainTable ... JOIN ViceTable ON ViceTable.key=MainTable.refKey。 ⑤ "otherKey": Object，自定义关键词，名称和以上系统关键词不一样，且原样返回上传的值 |
① 查询User数组，最多5个： "count":5 ② 查询第3页的User数组，每页5个： "count":5, "page":3 ③ 查询User数组和对应的User总数： "[]":{ "query":2, "User":{} }, "total@":"/[]/total" 总页数、是否有下一页等信息可通过 total,count,page 得出， 总页数 int totalPage = Math.ceil(total / count) 是否有下一页 boolean hasNextPage = total > count*page 是否为第一页 boolean isFirstPage = page <= 0 是否为最后一页 boolean isLastPage = total <= count*page ... ④ Moment INNER JOIN User LEFT JOIN Comment： "[]":{ "join": "&/User/id@,</Comment/momentId@", "Moment":{}, "User":{ "name~":"t", "id@": "/Moment/userId" }, "Comment":{ "momentId@": "/Moment/id" } } ⑤ 每一层都加当前用户名： "User":{}, "[]":{ "name@":"User/name", //这里name为自定义关键词 "Moment":{} } |
| 对象关键词，可自定义 | "@key":Object，@key为 Table:{} 中{}内的关键词，Object的类型由@key指定 ① "@combine":"&key0,|key1,!key2,..."，条件组合方式，| 可省略 ② "@column":"column;function(arg)..."，返回字段 ③ "@order":"column0+,column1-..."，排序方式 ④ "@group":"column0,column1..."，分组方式。如果@column里声明了Table的id，则id也必须在@group中声明；其它情况下必须满足至少一个条件: 1.分组的key在@column里声明 2.Table主键在@group中声明 ⑤ "@having":"function0(...)?value0;function1(...)?value1;function2(...)?value2..."，SQL函数条件，一般和@group一起用，函数一般在@column里声明 ⑥ "@schema":"sys"，集合空间(模式)，非默认的值可通过它来指定 ⑦ "@database":"POSTGRESQL"，跨数据库，非默认的值可通过它来指定 ⑧ "@role": "OWNER"，来访角色，包括 UNKNOWN,LOGIN,CONTACT,CIRCLE,OWNER,ADMIN， 可自定义其它角色并重写 Verifier.verify 等相关方法来自定义校验。 ⑨ "@otherKey": Object，自定义关键词，名称和以上系统关键词不一样，且原样返回上传的值 |
① 搜索name或tag任何一个字段包含字符a的User列表： "name~":"a", "tag~":"a", "@combine":"name~,tag~" ② 只查询id,sex,name这几列并且请求结果也按照这个顺序： "@column":"id,sex,name" ③ 查询按 name降序、id默认顺序 排序的User数组： "@order":"name-,id" ④ 查询按userId分组的Moment数组： "@group":"userId,id" ⑤ 查询 按userId分组、id最大值>=100 的Moment数组： "@column":"userId;max(id)", "@group":"userId", "@having":"max(id)>=100" 还可以指定函数返回名： "@column":"userId;max(id):maxId", "@group":"userId", "@having":"maxId>=100" ⑥ 查询 sys 内的 User 表： "@schema":"sys" ⑦ 查询 PostgreSQL 数据库的 User 表： "@database":"POSTGRESQL" ⑧ 查询当前用户的动态： "@role":"OWNER" ⑨ 从pictureList获取第0张图片： "@position":0, //这里@position为自定义关键词 "firstPicture()":"getFromArray(pictureList,@position)" |