RESTful的Api设计之统一接口

内容根据 Java RESTful Web Service实战 [韩陆著] 整理

REST统一接口

REST式的Web服务和RPC式的Web服务在接口定义上的区别是，REST使用HTTP通用方法作为统一接口的标准词汇，REST式的Web服务所提供的方法信息都在HTTP方法里，而RPC式的web服务所提供的方法信息在SOAP/HTTP信封里（其封装的格式通常是HTTP或者是SOAP），每个RPC式的web服务都会公布一套符合自己商业逻辑的方法词汇。

要定义严谨的REST的统一接口，就需要真正理解HTTP方法的幂等性

1. 安全性:代表安全的REST的接口，是指外系统对该接口的访问，不会使服务器端资源的状态发生改变。
2. 幂等性:幂等性是指外系统对同一REST接口的多次访问，得到的资源是相同的。

资源方法的命名

标准的命名方式应该是单数的同步操作以资源名称命名。批量的同步操作以资源名称的复数名称命名。比如这个API是用与同步设备的，那么命名可以使用device和devices.如果担心与普通查询业务资源地址混淆。那可以在资源路径中增加查询或者路径参数。比如 device/id=1&source=a_b device/b/a等

媒体类型的选择

1. 媒体类型 HTTP中方法中执行写操作的非安全的HTTP方法，需要考虑请求实体媒体和响应实体媒体类型。（例如 PUT,POST）请求实体媒体类型使用HTTP头的Content Type 定义。响应实体媒体类型使用HTTTP头的Accpt定义。
   
   1. 在服务端 @Consumes() 定义了服务端请求实体的媒体类型。
   2. @Produces() 定义了服务器产生的响应实体的媒体类型。

@GET

HTTP的GET方法用于读取资源。GET的方法是幂等的。GET方法也是安全的。如果获取的信息资源状态和资源的值发生变化，就不能使用GET方法。而是使用POST方法

• 另外我们一并介绍HEAD方法和OPTIONS方法
  
  • HEAD方法和和OPTIONS方法与GET方法类似，是安全和幂等的。只不过HEAD方法从服务端返回值不包括HTTP实体。
  • OPTIONS用于读取资源所支持的所有HTTP请求方法

@PUT

PUT方法是一种写操作的HTTP请求。REST使用HTTP的PUT方法更新和添加资源。PUT方法是幂等的但不是安全的。

• 如何区分何时使用PUT
  
  • 更新一定使用PUT方法
  • 添加资源 创建通常选用POST方法。PUT方法的唯一的应用场景是，客户端发起请求时，在同一数据中总可以提供唯一的主键值。

@DELETE

DELETE方法是幂等的，既多次删除同一份数据，在服务器端产生的改变是相同的。

@POST

• POST方法是一种写操作的HTTP请求，RPC的所有写操作均是使用POST方法。而REST只使用HTTP的POST方法添加资源。

• POST 既不幂等也不安全。

WebDev扩展方法

• WebDAV ,基于Web的分布式创作与版本控制，是IERF的RFC4918规范，是针对HTTP1.1的一组扩展，该协议允许用户一些做方式编辑和管理远程web服务器上的文件。WEBDAV在HTTP方法的基础上增加可如下的方法，

• 如图
  

• 如果遵从ROA，那就不应该使用HTTP标注方法之外的方法。凡是如果业务需要超出标准方法所及，那就可以使用如下注解实现对WebDev的支持。