Efficient JAX-RS: Conditional Gets & Puts

This post discusses how to leverage features in the JAX-RS API to execute RESTful operations based on conditions/criteria in order to aid with scalability and performance. It covers:

• Which HTTP headers are involved
• Which JAX-RS APIs to use
• Details of the entire request-response flow

Required Components

Must Know HTTP Headers

It would be awesome if you have a basic understanding of (at least some of) these HTTP headers (since these form an important part of the JAX-RS features discussed in this post). These are best referred from the official HTTP specification document:

• Cache-Control
• Expires
• Last-Modified
• If-Modified-Since
• If-Unmodified-Since
• ETag
• If-None-Match

JAX-RS APIs

• CacheControl: Again, just a simple class. Why not read one of my existing blog posts on this topic?
• EntityTag: JAX-RS equivalent (simple class) of the HTTP ETag header
• Request: the main API which contains utility methods to evaluate the conditions which in turn determine the criteria for access

What Are We Trying to Achieve?

A simple interaction with a JAX-RS service can be as follows:

• Client sends a GET request
• Server replies back with the requested resource (with a HTTP 200 status)
• It also sends the Cache-Control & Last-Modified headers in response

Cache-Control defines the expiration semantics (along with other fine grained details) for the resource on the basis of which the client would want to:

• Revalidate its cache, i.e. invoke the GET operation for same resource (again).
• Make sure it does so in an efficient/scalable/economic manner, i.e. not repeat the same process of exchanging data (resource info) if there are no changes to the information that has been requested.

Common sense stuff, right?

Let’s look at how we can achieve this.

Option 1

Leverage the Last-Modified and If-Modified-Since headers

• Server sends the Cache-Control and Last-Modified headers as a response (for a GET request).
• In an attempt to refresh/revalidate its cache, the client sends the value of the Last-Modified header in the If-Modified-Since header when requesting for the resource in a subsequent request.
• Request#evaluatePreconditions(Date) determines whether or not the value passed in the If-Modified-Since header is the same as the date passed to the method (ideally the modified date would need to extracted from somewhere and passed on this method).

(Slightly) Advanced Usage

ETag header in action

• In addition to the Last-Modified header, the server can also set the ETag header value to a string which uniquely identifies the resource and changes when it changes, e.g. a hash/digest.
• The client sends the value of the ETag header in the If-None-Match header when requesting for the resource in a subsequent request.
• Then its over to the Request#evaluatePreconditions(EntityTag).

Note: With the Request#evaluatePreconditions(Date,EntityTag) the client can use both last modified date as well as the ETag values for criteria determination. This would require the client to set the If-Modified-Since header

Making Use of the API Response…

In both the scenarios:

• If the Request#evaluatePreconditions method returns null, this means that the pre-conditions were met (the resource was modified since a specific time stamp and/or the entity tag representing the resource does not match the specific ETag header) and the latest version of the resource must be fetched and sent back to the client.
• Otherwise, a HTTP 304 (Not Modified) response is automatically returned by the Request#evaluatePreconditions method, which can be returned as is.

Please note …

• Choice of ETag: This needs to be done carefully and depends on the dynamics of your application. What are the attributes of your resource whose changes are critical for your clients? Those are the ones which you should use within your ETag implementation.
• Not a magic bullet: Based on the precondition evaluation, you can help prevent unnecessary exchange of data b/w client and your REST service layer, but not between your JAX-RS service and the backend repository (e.g. a database). It’s important to understand this.

Can I Only Improve My GETs …?

No! the HTTP spec cares abut PUT operations as well; and so does the JAX-RS spec. :-)

• Server sends the Cache-Control & Last-Modified headers as a response (for a GET request).
• In an attempt to send an updated value of the resource, the client sends the value of the Last-Modified header in the If-Unmodified-Since header.
• Request#evaluatePreconditions(Date) determines whether or not the value passed in the If-Unmodified-Since header is the same as the date passed to the method (in your implementation).

So the Essence Is...

• If the API returns a non null response, this means that the pre-conditions were not met (HTTP 412) i.e. the resource was in fact modified after the time stamp sent in the If-Unmodified-Since header, which of course means that the caller has a (potentially) stale (outdated) version of the resource.
• Otherwise (for a null output from the API), its a hint for the client to go ahead and execute the update operation.
• In this scenario, what you end up saving is the cost of update operation executed against your database in case the client’s version of the resource is outdated.

Further reading

Cheers!