The Rails fresh_when method is a powerful tool for conditionally caching resources via HTTP. However there are some pitfalls. For one, fresh_when only supports the default render flow in a controller; if a client’s cache is not fresh, it will just render the related view. We cannot utilize things like render json:.

Fortunately, Rails provides us with more tools to work with HTTP conditional caching. Some of the basics behind HTTP conditional caching are assumed in this post. If you haven’t already, or you just need a refresher take a look at Introduction to Conditional HTTP Caching with Rails.

Let’s work with a simple Rails blog application which renders posts as JSON.

# app/controllers/posts_controller.rb
class PostsController < ApplicationController
  def show
    @post = Post.find(params[:id])
    render json: @post
  end
end

# config/routes
Rails.application.routes.draw do
  resources :posts, only: [:show]
end

What if we wanted to allow the client to conditionally cache this content? Rails provides us with the stale? method which takes a resource and checks to see if the ETag provided by the client via the If-None-Matches header matches the one which represents the resource’s current state. The stale? method can also work with the If-Modified-Since header. It will check if the resource’s updated_at has been modified since the timestamp provided by If-Modified-Since. To utilize this, we just need to wrap our render call with a call to stale?.

class PostsController < ApplicationController
  def show
    @post = Post.find(params[:id])

    if stale?(@post)
      render json: @post
    end
  end
end

If we make a request to the individual post we’ll get something similar to the following response:

curl -i http://localhost:3000/posts/1

HTTP/1.1 200 OK
Etag: "f049a9825a0239db3d01ead65a5ea522"
Last-Modified: Tue, 02 Dec 2014 18:31:42 GMT
Content-Type: application/json; charset=utf-8
Cache-Control: max-age=0, private, must-revalidate
Server: WEBrick/1.3.1 (Ruby/2.1.5/2014-11-13)
Date: Tue, 02 Dec 2014 18:31:48 GMT
Content-Length: 93
Connection: Keep-Alive

{"post":{"title":"Blog post 0","body":"lorem ipsum","created_at":"2014-11-12T15:30:34.025Z"}}%

If we take a look at our Rails server log, we’ll see something similar to the following:

Started GET "/posts/1" for 127.0.0.1 at 2014-12-02 13:38:18 -0500
Processing by PostsController#show as */*
  Parameters: {"id"=>"1"}
  Post Load (0.2ms)  SELECT  "posts".* FROM "posts"  WHERE "posts"."id" = $1
LIMIT 1  [["id", 1]]
Completed 200 OK in 1ms (Views: 0.3ms | ActiveRecord: 0.2ms)

Now if we make a request with the If-None-Match header set to the ETag that the server provided us with earlier:

curl -i -H 'If-None-Match: "f049a9825a0239db3d01ead65a5ea522"' http://localhost:3000/posts/1

We’ll now receive a 304 Not Modified status for our request.

HTTP/1.1 304 Not Modified
Etag: "f049a9825a0239db3d01ead65a5ea522"
Last-Modified: Tue, 02 Dec 2014 18:31:42 GMT
Cache-Control: max-age=0, private, must-revalidate
Server: WEBrick/1.3.1 (Ruby/2.1.5/2014-11-13)
Date: Tue, 02 Dec 2014 18:32:53 GMT
Connection: Keep-Alive

If we take a look at our Rails log we’ll notice that the server skipped over the process of rendering the JSON all together:

Started GET "/posts/1" for 127.0.0.1 at 2014-12-02 13:38:55 -0500
Processing by PostsController#show as */*
  Parameters: {"id"=>"1"}
  Post Load (0.2ms)  SELECT  "posts".* FROM "posts"  WHERE "posts"."id" = $1
LIMIT 1  [["id", 1]]
Completed 304 Not Modified in 1ms (ActiveRecord: 0.2ms)

In this trivial example our gain is not huge. However with more complicated JSON objects this can be a very useful. A common example is a larger JSON response built via ActiveModel::Serializers. Combined with key-based caching in ActiveModel::Serializers this can be a powerful tool. We can cache individual items with russian doll caching, and then cache the entire response via HTTP caching.

Further Reading

• Fast JSON APIs in Rails with Key-Based Caches and ActiveModel::Serializers
• How to Evaluate Your Rails JSON API for Performance Improvements

Organizing our API

Building our API we set out to achieve a few goals:

• Make the API flexibile and decoupled from the front-end implementation
• Leverage HTTP caching whereever possible
• Ensure it could handle high scale

Making the API decoupled from it’s front-end implmentation ensured that any design or data usage changes made would not require a change in 2 areas of our code base, the JavaScript application and the Rails application / API.

Leveraging HTTP caching gave us 2 gains. The first is we wanted to leverage an individual user’s caching in their browser, reducing the amount of data we needed to send back to the user. The 2nd gain, which in my opinion was the bigger gain was the ability to add a caching layer in front of the entire response body through Rack::Cache.

ActiveModel::Serializers

(ActiveModel::Serializers)[https://github.com/rails-api/active_model_serializers] is a great library for encapsulating object serialization for JSON APIs in Rails. It provides a great Object Oriented approach to serialization. If you haven’t seen it before I highly recommend checking it out. Furthermore, it implements caching through Rails.cache to provide the ability to cache serialization of objects using (key based expiration)[http://37signals.com/svn/posts/3113-how-key-based-cache-expiration-works]. This provided us with some very nice, quick and easy caching of our serialized data. Thoughtbot has a great (article on ActiveModel::Serailziers and caching)[http://robots.thoughtbot.com/post/50091183897/fast-json-apis-in-rails-with-key-based-caches-and] so I’m not going to get into the details of it.

With this caching we were able to get a great method of caching our serialization. However we wanted more. Our models have a lot of associations which can be re-used through Russian doll caching. We implemented (this pull request)[https://github.com/rails-api/active_model_serializers/pull/307] in or serializers in order to benefit from side-effect free russian doll caching. With this in mind we could reuse caches just as easily across requests when possbile.

Rack::Cache

Leveraging Rack::Cache in front of the API was one of the biggest wins for us. Rails has Rack::Cache active in production mode by default. However if you aren’t using HTTP caching properly you won’t see the benfits. There are many articles on the details of the various HTTP caching mechanisms that can be used. From cache-control headers, to etags and last-modified time stamps. Before we jump into the details let me explain why Rack::Cache was so useful.

When leveraging russian doll caching for our serialization we were able to get very fast serialization for our objects. However this typically lead to lots of memcached requests for fetcihng the individual pieces of the cache. This was not optimal. Our architecture benefited from the fact that one parent object could be used to determine the freshess of a cache. Think of the classic todo list example. Where individual todos in a list are cached as part of the entire todo list. If any individual todo-item in the list expires, then the list itself is expired. So, if we were using ActiveModel::Serialziers with caching, it would hit a cache for each item in the todo list.

Outline

• Weeks JSON public to all users
• Picks public because it’s route is built from user ID.
• ActiveModel::Serializers
• Rack::Cache

class SteelController < ActionController::Metal
  include ActionController::Rendering

  def show
    render :text => "Here is some text"
  end
  include ::NewRelic::Agent::Instrumentation::ControllerInstrumentation
  add_transaction_tracer :show
end

While this works, the problem remains that now you will need to add a transaction tracer for each and every controller action you add.

With this in mind I went in search of a better solution which could streamline the solution. Digging around the NewRelic RPM gem internals I was able to find the ‘magic’ behind the way New Relic integrates into requests. Within lib/new_relic/agent/instrumentation/rails3/action_controller.rb you can find the following:

DependencyDetection.defer do
  @name = :rails3_controller

  depends_on do
    defined?(::Rails) && ::Rails::VERSION::MAJOR.to_i == 3
  end

  depends_on do
    defined?(ActionController) && defined?(ActionController::Base)
  end

  executes do
    NewRelic::Agent.logger.debug 'Installing Rails 3 Controller instrumentation'
  end

  executes do
    class ActionController::Base
      include NewRelic::Agent::Instrumentation::ControllerInstrumentation
      include NewRelic::Agent::Instrumentation::Rails3::ActionController
    end
  end
end

Which handles including the various instrumentation tools for ActionController. With this in mind we can follow the same logic in our API BaseController:

require 'new_relic/agent/instrumentation/controller_instrumentation'
require 'new_relic/agent/instrumentation/rails3/action_controller'
require 'new_relic/agent/instrumentation/rails3/errors'

class Api::V1::BaseController < ActionController::Metal
	include ActionController::Instrumentation
	include ActionController::Rescue
	
	# ...
	
	# In order to enable NewRelic RPM monitoring in the API we'll need to include it
	include NewRelic::Agent::Instrumentation::ControllerInstrumentation
	include NewRelic::Agent::Instrumentation::Rails3::ActionController
	include NewRelic::Agent::Instrumentation::Rails3::Errors
		
end

One issue we’ve run into we’ve run into is related to the asset pipeline and serving assets from a custom asset host.

For example:

config/environments/production.rb

Example::Application.configure do
	config.action_controller.asset_host = "//static.example/com"
end

Typically the usage behind this in a rails application is masked, whenever you use image_tag the image will be routed to the asset host on its own behind the scenes. However since we’re inheriting from ActionController::Base there is some work to be done. We’ll need to include a couple of modules and ensure that the load hooks are loaded in our base controller, something that happens behind the scenes when inheriting from ActionController::Base.

class Api::V1::BaseController < ActionController::Metal
	include AbstractController::AssetPaths
	
	include ActionController::Redirecting
	include ActionController::Rendering
	include ActionController::Caching
	include ActionController::Renderers::All
	include ActionController::ConditionalGet
	include ActionController::ParamsWrapper
	include ActionController::MimeResponds
	
	ActiveSupport.run_load_hooks(:action_controller, self)
end

Of course, depending on what your application is using your mileage may vary. Our actual API BaseController looks something more like:

class Api::V1::BaseController < ActionController::Metal
	include AbstractController::AssetPaths
	include ActionController::Helpers

	include ActionController::Redirecting
	include ActionController::Rendering
	include ActionController::Caching
	include ActionController::Renderers::All
	include ActionController::ConditionalGet
	include ActionController::ParamsWrapper

	include ActionController::MimeResponds
	include ActionController::RequestForgeryProtection
	include AbstractController::Callbacks

	include ActionController::Instrumentation
	include ActionController::Rescue

	Rails.application.routes.default_url_options = ActionMailer::Base.default_url_options
	include Rails.application.routes.url_helpers

	append_view_path "#{Rails.root}/app/views"

	protect_from_forgery

	ActiveSupport.run_load_hooks(:action_controller, self)
end

Be sure to check out the rails ActionController::Base to see what else is included by default and tweak as you see fit.

Instead, I set out to build a back end service which would consume our third party API and we could interact with on the front end. However, I did not want to spend a great deal of time on building this midpoint between the services.

Ruby and Sinatra to the Rescue

Armed with the task at hand I set out to build the simplest approach possible to begin consuming our third party API as quickly as possible. I started out with Rails and a look into ActiveResource but quickly found that there was to much overhead and complexity for what I needed. With this in mind I decided to move onto a simple Sinatra application which would aim to mimic the third party services in API methods and forward requests for us.

For our test case, let’s look at the Twitter API. Note, Twitter does in fact support a JSONP service so this isn’t really necessary. We are simply using it as a test case for the post.

Fetching a user’s timeline

require 'sintra'
require 'net/http'

get "/1/statuses/user_timeline" do
    uri = URI::HTTP.build(
        :host => api.twitter.com,
        :path => request.path_info,
        :query => request.query_string
    )

    content_type 'application/json', :charset => 'utf-8'

    Net::HTTP.get(uri)
end

In order to fetch a user’s timeline we will need to make a request to the following API path: /1/statuses/user_timeline. Along with this path the API documentation by twitter specifies that we can send various parameters along in the query string. What we have done here is we created a path which matches twitter’s and from there we access the request information provided by Sinatra. We build a URI using the API URL, request.path, and request.query. This will allow us to quickly forward the request to Twitter’s API through a NET::HTTP.get request.

Now that we’ve done that we can either mount our Sinatra app somewhere in the same domain or proxy requests to it on another domain. In my case, I’ve set up a simple proxy through Apache at /services.

<IfModule mod_proxy.c>
    ProxyRequests Off
    ProxyVia On

    <Proxy *>
        AddDefaultCharset off
        Order deny, allow
        Allow from all
    </Proxy>

    ProxyPass /services http://127.0.0.1:9393
    ProxyPassReverse /services http://127.0.0.1:9393
</IfModule>

So assuming I have my Sinatra application up and running on port 9393. I now have a proxy which will forward all requests to /services in my web application to the Sinatra application. This will then forward all requests to the Twitter API and return the results. Visit the mod_proxy documentation for more information about HTTP proxies with Apache.

Drying up our application

In our case right now we have a single method that we are forwarding, but what if we wanted to support more API methods provided by twitter. Well we could go ahead and write out each method and its block, or we could take advantage of the flexibility we have available to us.

require 'sinatra'
require 'net/http'

def api_request(path, query_string)
    uri = URI::HTTP.build(
        :host => api.twitter.com,
        :path => path,
        :query => query_string
    )

    Net::HTTP.get uri
end

request_handler = -> do
    content_type = 'application/json', :charset => 'utf-8'
    api_request request.path_info, request.query_string
end

%w{
    /1/statues/user_timeline
    /1/statuses/mentions
    /1/statuses/retweeted_by_me
}.each { |route| get route, &request_handler }