Skip to content

Resource versioning

Jump to bottom
Captain-P-Goldfish edited this page Nov 23, 2019 · 5 revisions

@available since 1.1.0

This page will shortly explain how resource versioning is implemented and how it can be used.

NOTE: as long as the service provider configuration has not set its etag-support attribute to true all version fields will be ignored.

As described in RFC7232 in chapter 2.3.1:

The principle behind entity-tags is that only the service author knows the implementation of a resource well enough to select the most accurate and efficient validation mechanism for that resource, and that any such mechanism can be mapped to a simple sequence of octets for easy comparison. Since the value is opaque, there is no need for the client to be aware of how each entity-tag is constructed.

resource versioning SHOULD be implemented by the developer himself. However there is a default implementation coming with this framework that creates weak entity tags on resources that is used if the developer misses to set the version attribute. The default ETag implementation builds the string-representation of the returned resource calculates a SHA-1 hash value and encodes it in base64. This is of course not a reliable implementation but it was the best that I could provide. So if you set etag-support to true make sure you will implement etag generation accurately for your resources.

How to use?

When implementing e.g. a UserHandler class that extends the class ResourceHandlerand the develper needs to set the meta.version attribute within the resource. The rest is done by the framework. If the support for etags is set to true and the developer misses to set the meta.version attribute the default implementation is used.

What to do with the etags?

If returned to the client the client can add either one of the http request headers

  1. If-Match
  2. If-None-Match

the framework will evaluate these headers according to RFC7232.

response behaviour

  1. Client used the If-Match request header with an etag
    • etag does match
      • condition is satisfied request will be executed normally
    • etag does not match
      • http status 412 (Precondition failed) is returned with a dedicated error message that also contains the new etag
  2. Client used the If-None-Match request header with an etag
    • etag does match
      • 304 (Not Modified) with an empty response body is returned
    • etag does not match
      • condition is satisfied request will be executed normally
Clone this wiki locally