APIJSON

让接口和文档见鬼去吧!客户端定义服务端返回JSON的结构!Let interfaces and documents go to hell! Clients define JSON structures which server returned!

APIJSON

English Document

APIJSON是一种JSON传输结构协议。

客户端可以定义任何JSON结构去向服务端发起请求,服务端就会返回对应结构的JSON字符串,所求即所得。
一次请求任意结构任意数据,方便灵活,不需要专门接口或多次请求。
支持增删改查、模糊搜索、远程函数调用等。还能去除重复数据,节省流量提高速度!

从此HTTP传输JSON数据没有接口,更不需要文档!
客户端再也不用和服务端沟通接口或文档问题了!再也不会被文档各种错误坑了!
服务端再也不用为了兼容旧版客户端写新版接口和文档了!再也不会被客户端随时随地没完没了地烦了!

举个栗子(查询类似微信朋友圈动态列表):

请求:

{
    "[]": {                                               //请求一个array
        "page": 0,                                    //array条件
        "count": 2,        
        "User": {                                      //请求查询名为User的table,返回名为User的JSONObject
            "sex": 0                                   //object条件
        },
        "Moment": {
            "[email protected]": “/User/id”             //缺省依赖路径,从同级object的路径开始
        },
        "Comment[]": {                           //请求一个名为Comment的array 
            "page": 0,
            "count": 2,
            "Comment": {
                 "[email protected]": “[]/Moment/id”   //完整依赖路径
             }
        }
    }
}

点击这里测试

返回:

{
    "[]":{
        "0":{
            "User":{
                "id":38710,
                "sex":0,
                "phone":"1300038710",
                "name":"Name-38710",
                "head":"http://static.oschina.net/uploads/user/1218/2437072_100.jpg?t=1461076033000"
            },
            "Moment":{
                "id":470,
                "title":"Title-470",
                "content":"This is a Content...-470",
                "userId":38710,
                "pictureList":["http://static.oschina.net/uploads/user/585/1170143_50.jpg?t=1390226446000"]
            },
            "Comment[]":{
                "0":{
                    "Comment":{
                        "id":4,
                        "parentId":0,
                        "momentId":470,
                        "userId":310,
                        "targetUserId":14604,
                        "content":"This is a Content...-4",
                        "targetUserName":"targetUserName-14604",
                        "userName":"userName-93781"
                    }
                },
                "1":{
                    "Comment":{
                        "id":22,
                        "parentId":221,
                        "momentId":470,
                        "userId":332,
                        "targetUserId":5904,
                        "content":"This is a Content...-22",
                        "targetUserName":"targetUserName-5904",
                        "userName":"userName-11679"
                    }
                }
            }
        },
        "1":{
            "User":{
                "id":70793,
                "sex":0,
                "phone":"1300070793",
                "name":"Name-70793",
                "head":"http://static.oschina.net/uploads/user/1174/2348263_50.png?t=1439773471000"
            },
            "Moment":{
                "id":170,
                "title":"Title-73",
                "content":"This is a Content...-73",
                "userId":70793,
                "pictureList":["http://my.oschina.net/img/portrait.gif?t=1451961935000"]
            },
            "Comment[]":{
                "0":{
                    "Comment":{
                        "id":44,
                        "parentId":0,
                        "momentId":170,
                        "userId":7073,
                        "targetUserId":6378,
                        "content":"This is a Content...-44",
                        "targetUserName":"targetUserName-6378",
                        "userName":"userName-88645"
                    }
                },
                "1":{
                    "Comment":{
                        "id":54,
                        "parentId":0,
                        "momentId":170,
                        "userId":3,
                        "targetUserId":62122,
                        "content":"This is a Content...-54",
                        "targetUserName":"targetUserName-62122",
                        "userName":"userName-82381"
                    }
                }
            }
        }
    }
}

对比传统HTTP传输方式

开发流程 传统方式 APIJSON
接口传输 等服务端编辑接口,然后更新文档,客户端再按照文档编辑请求和解析代码 客户端按照自己的需求编辑请求和解析代码。没有接口,更不需要文档!客户端再也不用和服务端沟通接口或文档问题了!
兼容旧版 服务端增加新接口,用v2表示第2版接口,然后更新文档 什么都不用做!
客户端请求 传统方式 APIJSON
要求 客户端按照文档在对应url后面拼接键值对 客户端按照自己的需求在固定url后拼接JSON
结构 base_url/lowercase_table_name?key0=value0&key1=value1...
&currentUserId=100&loginPassword=1234

其中currentUserId和loginPassword只在请求部分接口时需要
base_url/{TableName0:{key0:value0, key1:value1 ...}, TableName1:{...}...
, currentUserId:100, loginPassword:1234}

其中currentUserId和loginPassword只在请求部分接口时需要
URL 不同的请求对应不同的url 相同的请求方法(GET,POST等)都用同一个url
键值对 key=value key:value
服务端操作 传统方式 APIJSON
解析和返回 取出键值对,把键值对作为条件用预设的的方式去查询数据库,最后封装JSON并返回给客户端 把RequestParser#parse方法的返回值返回给客户端就行
返回JSON结构的设定方式 由服务端设定,客户端不能修改 由客户端设定,服务端不能修改
客户端解析 传统方式 APIJSON
查看方式 查文档或等请求成功后看log 看请求就行,所求即所得。也可以等请求成功后看log
方法 解析JSONObject 可以用JSONResponse解析JSONObject或传统方式
客户端对应不同需求的请求 传统方式 APIJSON
User base_url/get/user?id=1 base_url/get/{"User":{"id":1}}
Moment和对应的User 分两次请求
Moment: base_url/get/moment?userId=1
User: base_url/get/user?id=1
base_url/get/{"Moment":{"userId":1}, "User":{"id":1}}
User列表 base_url/get/user/list?page=0&count=3&sex=0 base_url/get/{"[]":{"page":0, "count":3, "User":{"sex":0}}}
Moment列表,每个Moment包括发布者User和前3条Comment Moment里必须有User的Object和Comment的Array
base_url/get/moment/list?page=0&count=3&commentCount=3
base_url/get/{"[]":{"page":0, "count":3, "Moment":{}, "User":{"[email protected]":"/Moment/id"}, "[]":{"count":3, "Comment":{"[email protected]":"[]/Moment/id"}}}}
User发布的Moment列表,每个Moment包括发布者User和前3条Comment base_url/get/moment/list?page=0&count=3&commentCount=3&userId=1 有以下几种方法:
①把以上请求里的"Moment":{}, "User":{"[email protected]":"/Moment/id"}改为"Moment":{"userId":1}, "User":{"id":1}

②或这样省去4条重复User
base_url/get/{"User":{"id":1}, "[]":{"page":0, "count":3, "Moment":{"userId":1}, "[]":{"count":3, "Comment":{"[email protected]":"[]/Moment/id"}}}}

③如果User之前已经获取到了,还可以这样省去所有重复User
base_url/get/{"[]":{"page":0, "count":3, "Moment":{"userId":1}, "[]":{"count":3, "Comment":{"[email protected]":"[]/Moment/id"}}}}
服务端对应不同请求的返回结果 传统方式 APIJSON
User {"status":200, "message":"success", "data":{"id":1, "name":"xxx"...}} {"status":200, "message":"success", "User":{"id":1, "name":"xxx"...}}
Moment和对应的User 分别返回两次请求的结果
Moment: {"status":200, "message":"success", "data":{"id":1, "name":"xxx"...}}
User: {"status":200, "message":"success", "data":{"id":1, "name":"xxx"...}}
{"status":200, "message":"success", "Moment":{"id":1, "content":"xxx"...}, "User":{"id":1, "name":"xxx"...}}
User列表 {"status":200, "message":"success", "data":[{"id":1, "name":"xxx"...}, {"id":2...}...]} {"status":200, "message":"success", "[]":{"0":{"User":{"id":1, "name":"xxx"...}}, "1":{"User":{"id":2...}}...}}
Moment列表,每个Moment包括发布者User和前3条Comment {"status":200, "message":"success", "data":[{"id":1, "content":"xxx"..., "User":{...}, "Comment":[...]}, {"id":2...}...]} {"status":200, "message":"success", "[]":{"0":{"Moment":{"id":1, "content":"xxx"...}, "User":{...}, "[]":{"0":{"Comment":{...}...}}}, "1":{...}...}}
User发布的Moment列表,每个Moment包括发布者User和前3条Comment {"status":200, "message":"success", "data":[{"id":1, "content":"xxx"..., "User":{...}, "Comment":[...]}, {"id":2...}...]} 以上不同请求方法的结果:
①{"status":200, "message":"success", "[]":{"0":{"User":{"id":1, "name":"xxx"...}, "Moment":{...}, "[]":{"0":{"Comment":{...}...}}}, "1":{...}...}}

②{"status":200, "message":"success", "User":{...}, "[]":{"0":{"Moment":{"id":1, "content":"xxx"...}, "[]":{"0":{"Comment":{...}...}}}, "1":{...}...}}

③{"status":200, "message":"success", "[]":{"0":{"Moment":{"id":1, "content":"xxx"...}, "[]":{"0":{"Comment":{...}...}}}, "1":{...}...}}

1.APIJSON不需要接口、文档及兼容旧版客户端的特性仅针对GET和HEAD请求,好在这两个在所有请求里占大部分。
2.base_url指基地址,一般是顶级域名,其它分支url都是在base_url后扩展。如base_url:http://www.google.com/ ,对应的GET分支url:http://www.google.com/get/ ,下同。
3.status,指返回结果中的状态码,200表示成功,其它都是错误码,值全部都是HTTP标准状态码。下同。
4.message,指返回结果中的状态信息,对成功结果或错误原因的详细说明。下同。
5.status和message总是在返回结果的同一层级成对出现。对所有请求的返回结果都会在最外层有一对总结式status和message。对非GET、HEAD请求,返回结果里面的每个JSONObject里都会有一对status和message说明这个JSONObject的状态。下同。

请求方法、URL、Request、Response对应关系总览

 方法及说明 URL Request Response
GET:普通获取请求,明文,可用浏览器调试 base_url/get/ {TableName:{…}},{…}内为限制条件。
例如获取一个id为1的Moment:
{"Moment":{"id":1}}
{TableName:{...}, "status":200, "message":"success"}
例如
{"Moment":{"id":1, "userId":1, "content":"APIJSON,let interfaces and documents go to hell !"}, "status":200, "message":"success"}
HEAD:普通获取数量请求,明文,可用浏览器调试 base_url/head/ {TableName:{…}},{…}内为限制条件。
例如
{"Moment":{"userId":1}},获取一个id为1的User所发布的Moment总数
{TableName:{"status":200, "message":"success", "count":10}, "status":200, "message":"success"}
例如
{"Moment":{"status":200, "message":"success", "count":10}, "status":200, "message":"success"}
POST_GET:安全/私密获取请求,非明文,用于获取密码、钱包等对安全性要求高的数据 base_url/post_get/ 最外层加一个"tag":tag,其它同GET 同GET
POST_HEAD:安全/私密获取数量请求,非明文,用于获取银行卡数量等对安全性要求高的数据 base_url/post_head/ 最外层加一个"tag":tag,其它同HEAD 同HEAD
POST:新增数据,非明文 base_url/post/ {TableName:{…}, "tag":tag},{…}中id由服务端生成,客户端不能传。
例如
{"Moment":{"userId":1, "content":"APIJSON,let interfaces and documents go to hell !"}, "tag":"Moment"}
{TableName:{"status":200, "message":"success", "id":1}, "status":200, "message":"success"}
例如
{"Moment":{"status":200, "message":"success", "id":1}, "status":200, "message":"success"}
PUT:修改数据,非明文 base_url/put/ {TableName:{"id":id,…}, "tag":tag},{…}中id必传。
例如
{"Moment":{"id":1,"content":"APIJSON,let interfaces and documents go to hell !"}, "tag":"Moment"}
同POST
DELETE:删除数据,非明文 base_url/delete/ {TableName:{"id":id}, "tag":tag},{…}中id必传,一般只传id。
例如
{"Moment":{"id":1}, "tag":"Moment"}
同POST

1.TableName指要查询的table的名称字符串。第一个字符为大写字母,剩下的字符要符合英语字母、数字、下划线中的任何一种。对应的值为内部所传字段符合对应Table的JSONObject,结构是{...}
2."tag":tag 后面的tag是非GET、HEAD请求中匹配请求的JSON结构的key,一般是要查询的table的名称,由服务端Request表中指定。
3.非GET、HEAD请求的方法、tag、结构必须和服务端Request表中指定的一一对应,否则请求将不被通过。

功能符

 键值对格式 功能与作用 使用示例
"key[]":{},后面是JSONObject 查询数组 "User[]":{"User":{"sex":1}},查询性别为女的一个User数组,请求完成后会变为 "User[]":{"0":{"User":{"id":38710,"sex":1,"name":"Tommy"...}}, "1":{"User":{"id":82001,"sex":1,"name":"Lemon"...}} ...}
"key{}":[],后面是JSONArray,作为key可取的值的选项 匹配选项范围 "id{}":[38710,82001,70793],查询id符合38710,82001,70793中任意一个的Object。一般用于查询一个数组。请求{"[]":{"User":{"id{}":[38710,82001,70793]}}}会返回一个User数组,例如上面那个。
"key{}":"条件0,条件1...",条件为任意SQL比较表达式字符串,非Number类型必须用''包含条件的值,如'a' 匹配条件范围 "id{}":">=80000,\<=100000",查询id在80000,100000中任意一个的Object。一般用于查询一个数组。请求{"[]":{"User":{"id{}":">=80000,\<=100000"}}}会返回一个User数组,例如上面那个。
"key()":"函数表达式", 函数表达式为 function(Type0:value0,Type1:value1...) 远程调用函数 ["isPraised()":"contains(Collection:praiseUserIdList,userId)"](http://139.196.140.118:8080/get/{"Moment":{"id":301,"isPraised()":"contains(Collection:praiseUserIdList,userId)"}}),请求完成后会调用 boolean contains(Collection collection, Object object) 函数,然后变为 "isPraised":true 这种(假设点赞用户id列表包含了userId,即这个User点了赞)。函数参数类型为Object时可用 value 替代 Object:value。
"[email protected]":"依赖路径",依赖路径为用/分隔的字符串 依赖引用 "[email protected]":"/User/id",userId依赖引用同级User内的id值,假设id=1,则请求完成后会变成 "userId":1
"key$":"SQL搜索表达式",任意SQL搜索表达式字符串,如 %key%, %k%e%y% 等 模糊搜索 "name$":"%m%",搜索包含m的名字。一般用于查询一个数组。请求 {"[]":{"User":{"name$":"%m%"}}} 会返回name包含"m"的User数组。
"key+":key指定类型的Object,且类型为Number,String,JSONArray中的一种。如 1,"apijson",["url0","url1"] 等。只用于PUT请求 增加/扩展 "praiseUserIdList+":[1],添加一个点赞用户id,即该用户点了赞
"key-":key指定类型的Object,同"key+" 减少/去除,与"key+"相反 "balance-":100.00,余额减少100.00,即花费了100元
"@key":key指定类型的Object @key为JSONObject中的关键字,作用各不相同,但都不作为查询匹配条件 ① 只查询id,sex,name这几列并且请求结果也按照这个顺序:
"@columns":"id,sex,name"
返回
{
  "id":1,
  "sex":0,
  "name":"Lemon"
}
② 从pictureList获取第0张图片:
[{
  "@position":0, //这里@position为自定义关键词
  "firstPicture()":"get(Collection:pictureList,int:@position)"
}](http://139.196.140.118:8080/get/{"User":{"id":38710,"@position":0,"firstPicture()":"get(Collection:pictureList,int:@position)"}})
返回
{
  "pictureList":["url0","url1"],
  "@position":0,
  "firstPicture":"url0"
}
...

使用方法

1.下载后解压APIJSON工程

Clone or download > Download ZIP > 解压到一个路径并记住这个路径。

你可以跳过步骤2和步骤3,用我的服务器IP地址 139.196.140.118:8080 来测试服务端对客户端请求的返回结果。

2.导入MySQL table文件

服务端需要MySQL Server和MySQLWorkbench,没有安装的都先下载安装一个。
我的配置是Windows 7 + MySQL Community Server 5.7.16 + MySQLWorkbench 6.3.7 和 OSX EI Capitan + MySQL Community Server 5.7.16 + MySQLWorkbench 6.3.8,其中系统和软件都是64位的。

启动MySQLWorkbench > 进入一个Connection > 点击Server菜单 > Data Import > 选择刚才解压路径下的APIJSON-Master/table > Start Import > 刷新SCHEMAS, 左下方sys/tables会出现添加的table。

3.用Eclipse for JavaEE或IntellIJ IDEA Ultimate运行服务端工程

如果以上编辑器一个都没安装,运行前先下载安装一个。
我的配置是Windows 7 + JDK 1.7.0_71 + Eclipse 4.6.1 + IntellIJ 2016.3 和 OSX EI Capitan + JDK 1.8.0_91 + Eclipse 4.6.1 + IntellIJ 2016.2.5

Eclipse for JavaEE

1.导入
File > Import > Maven > Existing Maven Projects > Next > Browse > 选择刚才解压路径下的APIJSON-Master/APIJSON(Server)/APIJSON(Eclipse_JEE) > Finish

2.运行
Run > Run As > Java Application > 选择APIJSONApplication > OK

IntellIJ IDEA Ultimate

1.导入
Open > 选择刚才解压路径下的APIJSON-Master/APIJSON(Server)/APIJSON(Idea) > OK

2.运行
Run > Run APIJSONApplication

4.用ADT Bundle或Android Studio运行客户端工程

可以跳过这个步骤,直接下载下方提供的客户端App。

如果以上编辑器一个都没安装,运行前先下载安装一个。
我的配置是Windows 7 + JDK 1.7.0_71 + ADT Bundle 20140702 + Android Studio 2.2 和 OSX EI Capitan +(JDK 1.7.0_71 + ADT Bundle 20140702)+(JDK 1.8.0_91 + Android Studio 2.1.2),其中系统和软件都是64位的。

ADT Bundle

1.导入
File > Import > Android > Existing Android Code Into Workspace > Next > Browse > 选择刚才解压路径下的APIJSON-Master/APIJSON(Android)/APIJSON(ADT) > Finish

2.运行
Run > Run As > Android Application

Android Studio

1.导入
Open an existing Android Studio project > 选择刚才解压路径下的APIJSON-Master/APIJSON(Android)/APIJSON(AndroidStudio) > OK

2.运行
Run > Run app

5.操作客户端App

选择发送APIJSON请求并等待显示结果。
如果默认url不可用,修改为一个可用的,比如正在运行APIJSON服务端工程的电脑的IPV4地址,然后点击查询按钮重新请求。

关于作者

TommyLemon:https://github.com/TommyLemon
如果有什么问题或建议可以发我邮件,交流技术,分享经验 ^_^

下载试用客户端App

APIJSONClientApp.apk

更新日志

https://github.com/TommyLemon/APIJSON/commits/master

欢迎Star,欢迎Fork

https://github.com/TommyLemon/APIJSON


Top Contributors

TommyLemon

Releases

-   大调整 zip tar
-   完成数据库查询缓存 zip tar
-   更改依赖解析 zip tar
-   改的是Server zip tar
-   解决多个AND,OR拼接问题 zip tar
-   1.5.1 zip tar
-   1.5.0 zip tar
-   1.1.0 zip tar
-   1.0.0 zip tar
-   0.9.8 zip tar
-   0.9.7 zip tar
-   0.9.5 zip tar
-   0.9.2 zip tar
-   0.9.1 zip tar