笔记：REST API 设计

Evernote Export

body, td {
font-family: 微软雅黑 Light;
font-size: 14pt;
}

REST API 设计

创建时间：	04/07/2015 Saturday 15:50
更新时间：	04/07/2015 Saturday 17:48
作者：	liker.xu

掌握JAX-RS 2.0标准
REST统一接口
资源定位
请求处理过程传输数据的格式
响应信息
内容协商的支持
资源地址信息的支持
HTTP通用方法[GET+PUT+POST+DELETE+OPTION]
安全性：对接口访问不会造成服务器端资源状态变化
幂等性：对统一接口多次访问得到的状态表述是相同

@GET(只读)：幂等+安全
避免设计不良的API（不存在写操作）
资源方法命名（单复数资源名词）
接口层方法名称上的注解？注解写在接口方法上，实现类无需再定义，测试时注册实现类

@HEAD：安全+幂等
返回值不包括HTTP实体

@OPTIONS：安全+幂等
用于读取资源所支持（Allow）的所有HTTP方法

@PUT（写操作）：更新或添加资源：幂等，多次插入或者更新同一份数据，不安全
更新操作
@Produces（服务器要生产的媒体类型-输出） target（“book”）.request(acceptMediaType)
@Consumes（服务器要消费的媒体类型-输入）Entity.entity(newBook,contentMediaTYPE)
javax.ws.rs.core.MediaType

@POST：既不幂等也不安全
创建资源（主键设置在服务器端）
REST-post（a）
RPC-post（p）：需要先解析出执行方法

@DELETE：幂等
返回值void
HTTP状态码：204

WebDEV拓展方法（不遵从ROA（面向资源架构）的拓展接口）P77
REST资源定位（URI及其参数）[可用性+可维护性+可拓展性]
一个URI对映一个资源，但一个资源可以对映多个URI

资源路径概览：scheme://host:port/path?queryString1&queryString2
GET /books?start=0&size=10
有次序（,）：GET /books/01,2002-12,2004
无次序（;）：GET /books/restful;program=java;type=web

查询参数>>查询条件>>查询作用域
分页查询列表数据：/query-resource/books?start=24&size=10
public Books getBooks(@QueryParam(“start”) final int start,@QueryParam(“size”) final int size)

排序并分页查询列表数据：/queryresource/sorted-books/limit=5%sort=pronouce
public Books getBooks(@QueryParam(“limit”) final int limit,@QueryParam(“sort) final String name)

查询单项数据：/query-resource/books?id=8

@Path（“{参数名称1：正则表达式}-{参数名称2：正则表达式}”）
public String getByCondition（@PathParam（“参数名称1”） final Integer a，@PathParam（“参数名称2”） final Integer b）
/path-resource/01,2012-12,2014
@Path(“{beginMonth:\d+},{beginYear:\d+}-{endMonth:\d+},{endYear:\d+}”)

@Path与@PathParam配合使用
@Path（”user：[a-zA-Z][a-zA-Z_0-9]*“）
@Produces(MediaType.TEXT_PLAIN)
public StringgetUserInfo(@PathParam(“user”) final String user,@DefaultValue(“Shne Yang”@QueryParam(“hometown” final String hometown)))

路径区间PathSegment（使资源类的一个方法支持更广泛的资源地址的请求）
@Path（”{region：.+}/shenyang/{district:\w+}“）
查询参数动态给定：将从哪胡说条件作为一个整体解析P85
PathSegment.getMatrixParameters();
@Path{“q/{condition}”}
public String getSomething(@PathParam final PathSegment condition,@MatrixParam(“program”) final String program,@MatrixSegment(“type”) final String type)
@MatrixParam表达了可接受的参数名称与类型

@FormParam：定义表单参数
Content-Type:application/x-www-form-urlencoed
@Path(“form-resource”)
public class FromResource(@DefaultValue(“liker”) @FormResource.USER final String user,@Encoded @FormParam(FormResourcep.PW) final String password,@Encoded @FormParam(FormResource.NPW) final String newpassword,@Enocded @FormParam(FormResource.VNPW) final String vertifictation) { ……
}
@Encode 禁用自动解码；@@DefaultValue 为客户端没有提供的参数值提供默认值

@BeanParam：自定义参数组合（用简洁的参数设计完成接口设计）
public String getAddress（@BeanParam MyClass param）{……}
public class MyClass(){
@HeaderParam(“accept”)
private String acceptParam;
@PathParam(“region”)
private String regionParam;
@PathParam(“district”)
private String stationParam;
@QueryParam(“station”)
private String stationParam;
@QueryParam(“vehicle”)
private String vehicleParam;
…….

}//定义了一系列REST方法会用到的参数类型

@CookieParam：用以匹配Cookie中的键值对信息
public String getHeaderParams（@CookieParam（”longitude“）final String logitude，@CookieParam（”latitude“）final String latitude）{…..}

@Context：解析上下文参数
public String getSomething（@Context final Application application,@Context final Request request,@Context final Providers providers）{…}
@Context final UriInfo uriInfo：路径信息上下文
@Context final HttpHeaders headers；