RESTful API中的header的作用（从Spring Data REST文档中译出）

        好久没有写博文了，最近想把自己的脚手架给全面restful了，正在研究rest api的验证授权，也看了下Spring Data REST这个框架，有意是从它下手。看到文档中关于rest中http header的一章自己获益不少，就翻译了下贡献出来，希望对大家有点帮助。

9. 根据headers在一定条件下才会诱发的操作

这个章节展示了Spring Data REST使用标准的HTTP headers来提升性能，条件化操作，和简单地展现出一个更精致的前端。

9.1. ETag, If-Match, and If-None-Match headers

ETag header提供了一个给资源加标签的方式，这可以阻止客户端覆盖彼此的操作同时也提供了减少不必要的调用的可能。

Example 3. A POJO with a version number

public class Sample {

 

    @Version Long version;

 

    Sample(Long version) {

        this.version = version;

    }

}

Spring Data Common的@Version 注解标记这个域是一个版本标识。

这个POJO，当被Spring Data REST作为一个REST资源导出时，将会有一个值为这个version域的ETag头。

我们可以在PUT,PATCH,或者DELETE那个资源时像这样有条件地加上一个If-Match header:

curl -v -X PATCH -H 'If-Match: <value of previous ETag>' ...

只有在资源的当前ETag状态匹配你请求时的If-Match header时，你的操作才会被执行。这阻止了客户端互相覆盖彼此。两个不同的客户端能够获取资源并且他们当时的资源响应header中拥有完全相同的ETag。如果他们总的一个客户端更新了这个资源，它将会产生一个新的ETag在应答中。但是第一次获取资源的另一个客户端仍然拥有老的header。如果他尝试去更新丙炔带着If-Match header，这个更新操作将会失败因为他们已经无法匹配上。取而代之的是，这个客户端会收到HTTP 412 Precondition Failed的消息。这个客户端解下来可以获取并处理这个错误消息。

If-None-Match header提供了另一个方案。相比有选择性地更新，If-None-Match允许有选择性地查询。

curl -v -H 'If-None-Match: <value of previous etag>' ...

这个命令默认会执行一个GET http调用。Spring Data REST将会在执行GET请求时检查If-None-Match headers，如果header 匹配了ETag，它将会总结出没有什么被修改过，而不会发送一个资源的拷贝给前端，只会发回一个HTTP 304 Not Modified状态码。语义上的解释是，当它读到“当这个支持的header的值不匹配服务端的version时，发送整个资源的数据；不然的话，不要发送数据回来。”

9.2. If-Modified-Since header

If-Modified-Since header提供了一个当上一次请求发生时检查一个资源是否被更新过来避免重新发送同样数据的方法。

Example 4. The last modification date captured in a domain type

@Document

public class Receipt {

 

      public @Id String id;

      public @Version Long version;

      public @LastModifiedDate Date date; 

 

      public String saleItem;

      public BigDecimal amount;

 

}

Spring Data Common的@ LastModifiedDate 注解允许用多种格式描述这个信息（JodaTime’s DateTime, legacy Java Date and Calendar, JDK8 date/time types, as well as long/Long）

带了这个域，Spring Data REST将会像这样返回一个Last-Modified 的头：

Last-Modified: Wed, 24 Jun 2015 20:28:15 GMT

这个值可以被捕获和用作后面的查询来避免在资源没有被更新的情况下两次获得同样的数据。

curl -H "If-Modified-Since: Wed, 24 Jun 2015 20:28:15 GMT" ...

用这个简单的命令，你正在询问的是 一个资源在那个时间开始之后被更新了话，重新获取它。如果是，你将会获得一个经过校正的Last-Modified header来更新你的客户端。如果不是，你将会获得一个HTTP 304 Not Modified 的状态码。

这个header完美地被格式化发回给解下来的查询中。