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返回数据，是否满足你的要求。测试工作完成！