今天，我在jersey wiki上看到关于 jersey的wadl相关内容，大致浏览了下，当然，大家都知道wadl是web service的接口描述文件，然而，想想我们以前那种基于json的接口描述文件，确实轻量了不少，我这里说“轻量”，主要是，很容易让人懂，wadl是基于xml的，很多人对于xml schema了解甚少，因此，通常初学者看到wadl都有一种生畏的感觉。
因此，我将我们两年前的REST接口文档拿了出来，这是我们当时的团队讨论的结晶，希望能给学习jersey或其他REST框架的同学们一点参考。
我们知道，基于REST的web service是以资源为中心的服务，因此，我们设计接口时，URI为接口进行定义，如，在用户管理系统中，对于角色的创建与获取，我们的接口为：
URI：/sys/{sysCode}/role/
对于这个接口，我们有POST与GET两个动作，分别代表创建角色和获取角色，我们分别来看一下这两个动作对应的接口输入输出是什么样的数据格式：
(1) post
描述：增加一个角色到某系统（如质量系统）
Request message header：
Accept: application/json Content-Type: application/json
Request message body：
{
name:张三, //角色名称
desc:取样人员 //角色描述
}
Response status：201
Response message header：
Content-type: application/json
Content-Location:http://www.jlerp.com/sys/001/role/001
Response message body：
{
uid:001,
name: 张三,
initCaptial: 'zhangsan',
desc:取样人员 //角色描述
}
(2) get
描述:获取所有角色
Request message header：
Accept: application/json Cache-Control: max-age=300
Response status：200
Response message header：
Content-type: application/json Cache-Control: max-age=300
Response message body：
{
roles:
[
{name:zhangsan,uid:001,initCaptial: 'zhangsan',desc:’’},
{name:zhangsan2,uid:002,initCaptial: 'zhangsan2',desc:’’}，
{name:zhangsan3,uid:003,initCaptial: 'zhangsan3',desc:’’}
]
}
关于对角色的删除，我们定义的接口是这样的：
URI：/sys/{sysCode}/role/deletebatch/
(1) post
描述：从系统批量删除角色
Request message header：
Accept: application/json Content-Type: application/json
Request message body：
{
Roles:[
{roleid:001},
{roleid:002}
]
}
Response status：204
Response message header：
Content-type: application/json
Response message body：
{
role:{
name:'zhangsan',
uid:001,
initCaptial:'zhangsan1',
desc:’’
}
}
可能到这里，有人会跳出来说，REST强调URI里不能包含动词，所有的动词只有HTTP本身的那几个：POST、GET、DELETE、PUT、HEAD……，我这里URI设计里用了delete，是不是就违反了REST的理念呢？这个问题我改日重新起一个话题来探讨吧，请你关注我的博客哦：）
至于其他接口定义，我就不一一列举了，大家参考后面的附件。
欢迎提出各种宝贵意见！
如果您觉得本文对您有益，请点击博文后的google广告，对作者表示支持，谢谢！