轻量级RESTful web service接口文档的编写规范文档

2008年与2009年期间，由于工作的原因，比较系统的学习了jersey这个REST框架，并且将其集成到我们的企业开发框架中，时到今日，公司已经完全放弃了原来的技术路线，这样一来，从jersey的研究从1.0.2.0以后，基本没有对后续的版本进行研究，不过，时常也关注一下它的发展动态，总的来说，jersey这个框架的发展还是相当缓慢的。

今天，我在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广告，对作者表示支持，谢谢！