How to build a Rails API server: Optimizing the framework

How to build a Rails API server: Optimizing the framework

I have been developing Rails JSON API applications for quite some time now, and I’d like to share a few of my setups and discuss why I do things this way. I’m starting today a series of articles that will cover up pretty much the steps I take every time I bootstrap a new Rails JSON API application.

One of the first things I do is to ensure I’m optimizing Rails for speed. I basically optimize the framework itself, prior coding any specific application logic.

You may have heard before that “Premature optimization is the root of all evil“. However, “Premature optimization is a phrase used to describe a situation where a programmer lets performance considerations affect the design of a piece of code”, which “can result in a design that is not as clean as it could have been or code that is incorrect, because the code is complicated by the optimization and the programmer is distracted by optimizing” (source: WikiPedia). This is not what we’re doing here: we’re just going to apply a few changes to Rails, and then basically forget about those and start coding in a framework that is optimized to serve our API.

Many of Rails functionalities are simply not needed when building an API server, and by stripping down Rails to a bare minimum we can actually achieve pretty significant performance increases.

Greenfield Ruby On Rails

Let’s first see what an empty project can achieve. I’m currently using Ruby 2.2.2 and Rails 4.2.1. Let’s create a new Rails application:

Let’s add a production server. For the scope of this post, it’s not really important what we use, as long as it’s a server that we can use in production. We are going to benchmark the results we get after applying our changes to Rails, so the absolute values resulting from our benchmarks are not as important as the relative improvements that we see in speed.

We’re going to use Puma, as it is now the recommended Ruby webserver by Heroku (and as I host most of my applications there, using it has become my default choice). Add it to the project Gemfile:

Then bundle install. Create a Puma configuration file  config/puma.rb  and set the following basic params:

We now need to set up a simple response page that we will hit with our benchmarks. We’re going to create a controller and an action that responds with a JSON body to the entry point /benchmarks/simple. To do so, let’s create  benchmarks_controller.rb:

Set the routes for this controller:

Start Puma in production:

Verify that Rails responds with our JSON body at the chosen entry point:

The server is up and ready. We can now benchmark our greenfield Rails application running with Puma. We will use the basic Apache Benchmark tool to do so.

This is actually not bad at all! A greenfield Rails project is able to sustain 2,138 req/sec. Obviously, this is without any application logic, nor database calls, but it is still a good starting point.

The Rails API gem

The Rails API gem is “a subset of a normal Rails application, created for applications that don’t require all functionality that a complete Rails application provides. It is a bit more lightweight, and consequently a bit faster than a normal Rails application. The main example for its usage is in API applications only, where you usually don’t need the entire Rails middleware stack nor template generation”.  Note that Rails API will be part of Rails 5, but for now we still have to include the gem:

Don’t forget to  bundle install. Then, change our  benchmarks_controller.rb to inherit from the Rails::API Action Controller:

Also, comment out in application_controller.rb :

Let’s try a new benchmark (portions omitted):

We now see a response rate of 2,369 req/sec, which is an increase in performance of ~11% over greenfield Rails. This is a modest improvement, but an improvement nonetheless.


Rails’ default JSON serializer isn’t the fastest out there, so let’s swap it for Oj:

Let’s run the benchmark with Oj (portions omitted):

We can see a small improvement here, which is practically irrelevant (~4%) as we hit 2,475 req/sec. The switch to Oj is going to be more relevant the bigger the JSON objects to serialize are, but at this stage it doesn’t hurt to keep Oj in here.


It is now time to give the final boost, by:

  • Removing unnecessary railties.
  • Using Rails’ ActionController::Metal instead of the base controllers that our BenchmarkController has inherited from until now.

First, remove unnecessary imports from application.rb (your mileage may vary – this is my standard setup and I’ve rarely needed anything else):

Second (and this is what is really going to make a difference), we’re going to create a new controller that all of our API controllers are going to inherit from. Let’s create our base  api_controller.rb :

As you can see, in this controller we define our custom render method. By default, I’ve already included the three modules that I basically use everywhere:

  • AbstractController::Callbacks which allows you to set callbacks such as before_action  in your controllers.
  • ActionController::RackDelegation which is needed to set the response_body  (called in the render  method).
  • ActionController::StrongParameters which allows you to use Strong Params in your controllers.

Other modules that you might want to include here are, for instance:

  • ActionController::HttpAuthentication::Token::ControllerMethods to use the authenticate_with_http_token  helper method if you are going to use token authentication in your API.
  • ActionController::HttpAuthentication::Basic::ControllerMethods to use the authenticate_with_http_basic  helper method if you are going to use basic authentication in your API.

Now for our benchmarks, let’s ensure that benchmarks_controller.rb  inherits from our newly created controller:

Here are the results of the benchmark that includes all of above changes (portions omitted):

This time the impact is notable, as we hit 4,206 req/sec.

Final Touch

With our latest ApiController, we are not using the controller that the Rails API gem exposes to us. Therefore, let’s remove the gem:

However, the Rails API gem did other interesting things under the hood, such as disabling some unnecessary Rails middleware. Since we removed it, we now need to do so ourselves. Add to application.rb:

Running the benchmark returns the previous results, so we can safely say we don’t need the Rails API gem anymore.


We have started with a greenfield Rails project, and have gradually applied changes to improve the speed performance of a simple benchmarked application:

Version Req/sec Increase
Greenfield Rails 2,138 -
+ Rails API Gem 2,369 +11%
+ Rails API Gem + Oj 2,475 +15%
+ Oj + ActionController::Metal + Custom middleware 4,206 +97%

Overall, we experienced an increase from 2,138 to 4,206 req/sec, which is doubling the initial performance of a greenfield Rails application.

For additional boosts, you may consider caching techniques (such as partial JSON caching), which are application dependent and are therefore out of scope here.

Happy API’ing!


  1. This is great stuff. Really excited to give it a go – but what will really teach me something is part 2! I’ll be on the lookout.

  2. Good stuff! Looking forward to part 2.

  3. Doesn’t Rails use MultiJson which uses Oj by default anyways?

    • Hello Chris,
      Prior to Rails 4.1 multi_json was indeed included in Rails, but it did not use Oj by default. From Rails 4.1 multi_json has actually been removed. This is why I had to use the oj_mimic_json gem here.

      Hope this clears up.

      • Yes thanks, that does. I just noticed that since I’m using Jbuilder for JSON templates it adds the dependency on multi_json. Cheers! Looking forward to the rest of the articles.

  4. Or

    This is a great tutorial Roberto thanks.
    I Implemented it on my local machine and i got approximately the same results as you got in your benchmark tests but after removing the sqlite gem and installing the postgres sql gem (pg) the results changed dramatically .
    without pg gem i got : Requests per second – 2058.28 [#/sec] (mean)
    with pg gem connected to heroku ps servers i got: Requests per second – 6.39 [#/sec] (mean)
    with pg gem connected to my local pg db i got: Requests per second – 867.03 [#/sec] (mean)
    BTW i left the controller as you described in the last section and did not created any request to the db yet.
    Do you know there is such a huge difference ?

    • Hi Or,
      Yes enabling database support has this kind of effect, probably because heavier objects get instanced. However, the relative speedup is still the same.

      The fact that you’re experiencing slow requests when connected to Heroku is exactly because you’re connecting to a remote server. If you run your app on Heroku you will not see these slowdowns.

  5. Austin

    Hi I hate to sound like a newbie but I followed this tutorial and the one here…

    I had relatively the same metrics as mentioned but I don’t know why and I’d like to find out more info about each of the modules so I know why they’re being used and if they’re a good fit for this project? I’ve been trying to learn more about the includes by tracking down the api docs for each of the modules but I’m having a hard time knowing why any of it is there in the first place? And the middlewares thing is still a mystery.

    But most importantly, when I switched from ActionController::Base to ActionController::Metal with this setup the server timing logs went away? EG: Completed 200 OK in 153ms (Views: 0.2ms | ActiveRecord: 15.8ms)

    What module got left out that I can put back in to get this functionality back? And is it configurable?

    Looking forward to your response!

    Thanks for the tutorial,


  6. Loved this post and just implemented this on my system! Looking forward to part 2!

  7. leonard

    Looking forward to part 2!

Leave a Reply