MyException - 我的异常网
当前位置:我的异常网» 编程 » RestFul Api 定义流程轨范

RestFul Api 定义流程轨范

www.MyException.Cn  网友分享于:2015-08-26  浏览:0次
RestFul Api 定义流程规范

(1)整理项目需求,编写Api需求文档,包括Api返回结果,查询参数等等。

(2)定义RestFul Api接口。

(3)测试RestFul Api接口。

(4)编写Api说明文档,包括Api的名称,路径,Http方法,请求参数,功能模板,返回结果等等,方便各模块研发人员和测试人员使用。

(5)测试人员测试Api,主要测试系统性能,还有一些特出场景测试,例如多线程,并发操作。编写Api测试报告

(6)Api接口调用,项目研发阶段。

备注:上述5和6可以同时进行,互不影响。主要产生三个Api文档:需求文档,说明文档,测试文档。


这里我总结一下2和3定义和测试RestFul api的一些经验,有疑问或者补充的地方请大家不吝赐教!

 一:RestFul api定义

(1)Url只能有名词

 之前在项目中定义Api,犯了一个很严重的问题。没有遵守RestFul规范,Api资源路径中还有大量的动词。

在RESTful架构中,每个url代表一种资源(resource),所以Url不能有动词,只能有名词。

(2)单数名词表示单个资源,复数名词表示所有资源。

例如:获取产品的API可以这样定义

获取单个产品:http://127.0.01:8080/AppName/rest/product/1

获取多个产品:  http://127.0.01:8080/AppName/rest/products

(3)使用子资源表达关系

如果一个资源与另外一个资源有关系,使用子资源:

/product/1/images/ 返回id=1的产品的所有图片

/product/1/image/1 返回id=1的产品的其中一个图片

(4)URL参数

情况1:http://127.0.01:8080/AppName/rest/product/1

URL最后的1就是参数,表示获取id=1的产品,则在api定义的时候1作为PathParam

@GET

@Path("/{productId}")

@Produces("application/json;charset=utf-8")
public Response editUser(@PathParam("productId") longproductId)

情况2:资源上传

前台部分:@FormDataParam表单参数


情况3:post提交对象参数,添加或者编辑对象



Api定义:


(5)选择Http方法

常用的HTTP动词有下面四个(括号里是对应的SQL命令)。
GET(SELECT):从服务器取出资源(一项或多项)。
POST(CREATE):在服务器新建一个资源。
PUT(UPDATE):在服务器更新资源(客户端提供改变后的完整资源)。
DELETE(DELETE):从服务器删除资源。

之前在项目中定义的Api,在选择Http方法上,也存在不足。例如用Post也实现更新资源或者删除资源。虽然在功能实现上没有什么问题,但是不够规范,Api定义显得杂乱。

二:RestFul Api测试

定义了RestFul Api,必须先做单元测试,确保Api可用,然后再交给别人去调用,这样才能确保工作进度。下面我就说说我测试Api的几种方法,具体怎么测试这里不做详细描述

(1)使用Apache的jmeter测试工具,很方便,可以批量测试Api,

 (2) 使用JerseyClient写测试程序。因为我们用的是jersey实现的RestFul。

 (3) 使用浏览器插件工具,我用的是火狐的插件RESTClient

(4)使用curl命令行工具。



使用工具测试Api,GET方法还好,如果是POST方法需要指定方法的Headers(数据格式),Body(请求参数),Api的url。

Body请求参数,如何获取呢,在这里我使用了Gson,先用java组织参数对象,然后用Gson将参数对象转化为json串。

    Gson gson = new Gson(); 

String wqtString = gson.toJson(wqt);


    System.out.println(wqtString)

举例说明:

我们框架中封装了一个查询参数WebQueryTerm。我获取到它的json串格式为:

{"page":{"number":1,"size":10,"total":0,"sorts":[{"field":"creationTime","type":"DESC"}]},"terms":[{"field":"appType","operator":"equal","value":"0"}]}

其中

page表示分页属性。number当前页,size一页显示多少条数据,

sorts排序:field表示排序字段。type表示排序类型,是desc降序还是asc升序

terms表示查询。field表示查询字段;operator表示是模糊查询Like还是精确查询Equal,value表示你输入的查询值。


这里简单说一下,怎么使用火狐的RESTClient。

(1)首先,在火狐浏览器菜单-附件组件-插件,中搜索RESTClient,并安装

(2)打开RESTClient,点击菜单Headers。输入自定义Request Headers。例如Name = Content-Type  Value=application/json 点击okay!

(3)选择Method,我选择Post,因为我测试获取应用列表,带分页,带查询条件。

(4)输入api资源的url:http://192.168.1.183:8080/osd/rest/app/apps

(5)输入上面的请求参数json串。

 (6)点击Send请求API。

结果查看:Response Headers如果Status Code =200 ok则表明API没有异常

再看Response Body返回数据,是否满足你的要求。测试工作完成!






文章评论

聊聊HTTPS和SSL/TLS协议
聊聊HTTPS和SSL/TLS协议
漫画:程序员的工作
漫画:程序员的工作
“懒”出效率是程序员的美德
“懒”出效率是程序员的美德
什么才是优秀的用户界面设计
什么才是优秀的用户界面设计
60个开发者不容错过的免费资源库
60个开发者不容错过的免费资源库
程序员的一天:一寸光阴一寸金
程序员的一天:一寸光阴一寸金
老程序员的下场
老程序员的下场
程序员应该关注的一些事儿
程序员应该关注的一些事儿
旅行,写作,编程
旅行,写作,编程
程序员和编码员之间的区别
程序员和编码员之间的区别
为啥Android手机总会越用越慢?
为啥Android手机总会越用越慢?
 程序员的样子
程序员的样子
Web开发人员为什么越来越懒了?
Web开发人员为什么越来越懒了?
程序员周末都喜欢做什么?
程序员周末都喜欢做什么?
写给自己也写给你 自己到底该何去何从
写给自己也写给你 自己到底该何去何从
5款最佳正则表达式编辑调试器
5款最佳正则表达式编辑调试器
Web开发者需具备的8个好习惯
Web开发者需具备的8个好习惯
程序员必看的十大电影
程序员必看的十大电影
我是如何打败拖延症的
我是如何打败拖延症的
做程序猿的老婆应该注意的一些事情
做程序猿的老婆应该注意的一些事情
不懂技术不要对懂技术的人说这很容易实现
不懂技术不要对懂技术的人说这很容易实现
为什么程序员都是夜猫子
为什么程序员都是夜猫子
10个帮程序员减压放松的网站
10个帮程序员减压放松的网站
程序员的鄙视链
程序员的鄙视链
亲爱的项目经理,我恨你
亲爱的项目经理,我恨你
2013年美国开发者薪资调查报告
2013年美国开发者薪资调查报告
鲜为人知的编程真相
鲜为人知的编程真相
一个程序员的时间管理
一个程序员的时间管理
看13位CEO、创始人和高管如何提高工作效率
看13位CEO、创始人和高管如何提高工作效率
总结2014中国互联网十大段子
总结2014中国互联网十大段子
我跳槽是因为他们的显示器更大
我跳槽是因为他们的显示器更大
Java 与 .NET 的平台发展之争
Java 与 .NET 的平台发展之争
如何成为一名黑客
如何成为一名黑客
我的丈夫是个程序员
我的丈夫是个程序员
要嫁就嫁程序猿—钱多话少死的早
要嫁就嫁程序猿—钱多话少死的早
如何区分一个程序员是“老手“还是“新手“?
如何区分一个程序员是“老手“还是“新手“?
“肮脏的”IT工作排行榜
“肮脏的”IT工作排行榜
中美印日四国程序员比较
中美印日四国程序员比较
编程语言是女人
编程语言是女人
代码女神横空出世
代码女神横空出世
Google伦敦新总部 犹如星级庄园
Google伦敦新总部 犹如星级庄园
程序员都该阅读的书
程序员都该阅读的书
初级 vs 高级开发者 哪个性价比更高?
初级 vs 高级开发者 哪个性价比更高?
2013年中国软件开发者薪资调查报告
2013年中国软件开发者薪资调查报告
Java程序员必看电影
Java程序员必看电影
那些争议最大的编程观点
那些争议最大的编程观点
程序员最害怕的5件事 你中招了吗?
程序员最害怕的5件事 你中招了吗?
程序员眼里IE浏览器是什么样的
程序员眼里IE浏览器是什么样的
科技史上最臭名昭著的13大罪犯
科技史上最臭名昭著的13大罪犯
软件开发程序错误异常ExceptionCopyright © 2009-2015 MyException 版权所有