REST是一种跨平台、跨语言的架构风格,jax-rs标准是在java领域,对rest式的web服务制定的实现标准, jersey是jax-rs标准的参考实现。
GET(SELECT):从服务器取出资源(一项或多项)。
POST(CREATE):在服务器新建一个资源。
PUT(UPDATE):在服务器更新资源(客户端提供完整资源数据)。
PATCH(UPDATE):在服务器更新资源(客户端提供需要修改的资源数据)。
DELETE(DELETE):从服务器删除资源。
REST(表述性状态转移),6个特点:客服端-服务器、无状态、可缓存、分层系统和按需编码。
要定义严谨的REST统一接口,就需要真正理解HTTP方法的安全性和幂等性。
安全性代表安全的REST接口,指外系统对该接口的访问,不会使服务器端的资源的状态发生改变。
幂等性指外系统对统一REST接口的多次访问,得到的资源状态是相同的。
GET方法的特性是幂等和安全的,但不意味着任何一个定义为处理GET请求的方法都是幂等和安全的。
资源方法命名:
GET /tickets # 获取ticket列表
GET /tickets/12 # 查看某个具体的ticket
POST /tickets # 新建一个ticket
PUT /tickets/12 # 更新ticket 12.
DELETE /tickets/12 #删除ticekt 12
URL命名通常有三种,驼峰命名法(serverAddress),蛇形命名法(server_address),脊柱命名法(server-address)。由于URL是大小写敏感的,如果用驼峰命名在输入的时候就要求区分大小写,一个是增加输入难度,另外也容易输错,报404。蛇形命名法用下划线,在输入的时候需要切换shfit,同时下划线容易被文本编辑器的下划线掩盖,支付宝用的是蛇形命名法,stackoverflow.com和github.com用的是脊柱命名法
URL命名原则
1、 URL请求采用小写字母,数字,部分特殊符号(非制表符)组成。
2、 URL请求中不采用大小写混合的驼峰命名方式,尽量采用全小写单词,如果需要连接多个单词,则采用连接符“_”连接单词
1.2. URL分级
第一级Pattern为模块,比如组织管理/orgz, 网格化:/grid
第二级Pattern为资源分类或者功能请求,优先采用资源分类
1.3. CRUD请求定义规范(RESTful)
如果为资源分类,则按照RESTful的方式定义第三级Pattern,
RESTful规范中,资源必须采用资源的名词复数定义。
/orgz/members
GET
获取成员列表
/orgz/members/120
GET
获取单个成员
/orgz/members
POST
创建成员
/orgz/members/120
PUT
修改成员
/orgz/members
PUT
批量修改
/orgz/members/120
PATCH
修改成员的部分属性
/orgz/members/120
DELETE
删除成员
1.4. 复杂查询请求定义规范(RESTful)
/module/tickets?state=open
GET
过滤
/module/tickets?sort=-priority
GET
排序
/module/tickets?sort=-priority,created_at
GET
排序
/module/tickets?sort=-updated_at
GET
排序
/module/tickets?state=closed&sort=-updated_at
GET
过滤+排序
/module/tickets?q=return&state=open&sort=-priority,created_at
GET
搜索+过滤+排序
/module/tickets/recently_closed
GET
一般数据请求
/module/tickets?fields=id,subject,customer_name,updated_at&state=open&sort=-updated_at
GET
指定返回列
/cars?offset=10&limit=5
GET
分页
URI设计上的一些技巧
1.使用_或-来让URI可读性更好
2.使用/来表示资源的层级关系
3.使用?用来过滤资源
4.,或;可以用来表示同级资源的关系
(三)下面列出了GET,DELETE,PUT和POST的典型用法:
1.GET
安全且幂等
获取表示
变更时获取表示(缓存)
200(OK) - 表示已在响应中发出
204(无内容) - 资源有空表示
301(Moved Permanently) - 资源的URI已被更新
303(See Other) - 其他(如,负载均衡)
304(not modified)- 资源未更改(缓存)
400 (bad request)- 指代坏请求(如,参数错误)
404 (not found)- 资源不存在
406 (not acceptable)- 服务端不支持所需表示
500 (internal server error)- 通用错误响应
503 (Service Unavailable)- 服务端当前无法处理请求
2.POST
不安全且不幂等
使用服务端管理的(自动产生)的实例号创建资源
创建子资源
部分更新资源
如果没有被修改,则不过更新资源(乐观锁)
200(OK)- 如果现有资源已被更改
201(created)- 如果新资源被创建
202(accepted)- 已接受处理请求但尚未完成(异步处理)
301(Moved Permanently)- 资源的URI被更新
303(See Other)- 其他(如,负载均衡)
400(bad request)- 指代坏请求
404 (not found)- 资源不存在
406 (not acceptable)- 服务端不支持所需表示
409 (conflict)- 通用冲突
412 (Precondition Failed)- 前置条件失败(如执行条件更新时的冲突)
415 (unsupported media type)- 接受到的表示不受支持
500 (internal server error)- 通用错误响应
503 (Service Unavailable)- 服务当前无法处理请求
3.PUT
不安全但幂等
用客户端管理的实例号创建一个资源
通过替换的方式更新资源
如果未被修改,则更新资源(乐观锁)
200 (OK)- 如果已存在资源被更改
201 (created)- 如果新资源被创建
301(Moved Permanently)- 资源的URI已更改
303 (See Other)- 其他(如,负载均衡)
400 (bad request)- 指代坏请求
404 (not found)- 资源不存在
406 (not acceptable)- 服务端不支持所需表示
409 (conflict)- 通用冲突
412 (Precondition Failed)- 前置条件失败(如执行条件更新时的冲突)
415 (unsupported media type)- 接受到的表示不受支持
500 (internal server error)- 通用错误响应
503 (Service Unavailable)- 服务当前无法处理请求
4.DELETE
不安全但幂等
删除资源
200 (OK)- 资源已被删除
301 (Moved Permanently)- 资源的URI已更改
303 (See Other)- 其他,如负载均衡
400 (bad request)- 指代坏请求
404 (not found)- 资源不存在
409 (conflict)- 通用冲突
500 (internal server error)- 通用错误响应
503 (Service Unavailable)- 服务端当前无法处理请求
(四)URL设计常见问题
1.POST和PUT用于创建资源时有什么区别?
POST和PUT在创建资源的区别在于,所创建的资源的名称(URI)是否由客户端决定。 例如为我的博文增加一个java的分类,生成的路径就是分类名/categories/java,那么就可以采用PUT方法。不过很多人直接把POST、GET、PUT、DELETE直接对应上CRUD,例如在一个典型的rails实现的RESTful应用中就是这么做的。 我认为,这是因为rails默认使用服务端生成的ID作为URI的缘故,而不少人就是通过rails实践REST的,所以很容易造成这种误解。
2.客户端不一定都支持这些HTTP方法吧?
的确有这种情况,特别是一些比较古老的基于浏览器的客户端,只能支持GET和POST两种方法。 在实践上,客户端和服务端都可能需要做一些妥协。例如rails框架就支持通过隐藏参数_method=DELETE来传递真实的请求方法, 而像Backbone这样的客户端MVC框架则允许传递_method传输和设置X-HTTP-Method-Override头来规避这个问题。
3.统一资源接口对URI有什么指导意义?(重点!!!!)
统一资源接口要求使用标准的HTTP方法对资源进行操作,所以URI只应该来表示资源的名称,而不应该包括资源的操作。 通俗来说,URI不应该使用动作来描述。例如,下面是一些不符合统一接口要求的URI:
GET /getUser/1
POST /createUser
PUT /updateUser/1
DELETE /deleteUser/1
4.响应代码的处理有必要吗?
HTTP的响应代码可用于应付不同场合,正确使用这些状态代码意味着客户端与服务器可以在一个具备较丰富语义的层次上进行沟通。 例如,201(“Created”)响应代码表明已经创建了一个新的资源,其URI在Location响应报头里。 假如你不利用HTTP状态代码丰富的应用语义,那么你将错失提高重用性、增强互操作性和提升松耦合性的机会。 如果这些所谓的RESTful应用必须通过响应实体才能给出错误信息,那么SOAP就是这样的了,它就能够满足了。
RESTFUL的api定义:
(1)Url只能有名词 在RESTful架构中,每个url代表一种资源(resource),所以Url不能有动词,只能有名词
(2)单数名词表示单个资源,复数名词表示所有资源。
获取单个产品: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)