{"id":7387,"date":"2015-10-06T16:15:11","date_gmt":"2015-10-06T13:15:11","guid":{"rendered":"http:\/\/www.webcodegeeks.com\/?p=7387"},"modified":"2015-12-16T11:13:59","modified_gmt":"2015-12-16T09:13:59","slug":"building-json-api-rails-5","status":"publish","type":"post","link":"https:\/\/www.webcodegeeks.com\/ruby\/building-json-api-rails-5\/","title":{"rendered":"Building a JSON API with Rails 5"},"content":{"rendered":"

Rails is great for making traditional server-rendered web applications. It has support for cookies, sessions, and other browser-specific functionality right out of the box. It\u2019s also great for building JSON APIs, but why include a whole bunch of functionality that we aren\u2019t going to use if what we want is to simply build a JSON API?<\/p>\n

That\u2019s where using Rails in --api<\/code> mode comes in handy. It gives us the power of Rails but with only the functionality that we\u2019re actually going to need for our JSON API.<\/p>\n

In this article, we\u2019ll investigate how to take advantage of the rails-api<\/code> gem, which, starting with Rails 5, now comes built in. We\u2019ll look at how to generate different types of JSON responses using ActiveModel::Serializer and how to cache our JSON serialization. Lastly, we\u2019ll look at how we can throttle requests to our API to avoid being taken down by abusive clients.<\/p>\n

Using Rails in \u201cAPI\u201d mode<\/h2>\n

Before Rails 5, we could already use Rails in \u201cAPI\u201d mode, but we had to do so through a different gem, namely the rails-api<\/a> gem. This past June, Santiago Pastorino opened up a pull-request<\/a> (which has since been merged) requesting that rails-api be merged into core Rails. This change will be included when Rails 5 launches.<\/p>\n

Using Rails 5 Right Now<\/h3>\n

It is possible to use Rails 5 right now, although you might want to proceed with caution since it isn\u2019t exactly ready for prime time. Here are the steps to take to use Rails 5 in API mode today:<\/p>\n

    \n
  1. Ensure you have Ruby 2.2 or higher.<\/li>\n
  2. Install Rails from master branch: git clone git@github.com:rails\/rails.git<\/code><\/li>\n
  3. Now it\u2019s time to generate a new Rails API application. We do that by passing the --api<\/code> directive to the rails new<\/code> command.<\/li>\n<\/ol>\n

    Because we are using Rails 5 before it\u2019s officially ready, we\u2019re going to need to run this command from within the directory we just cloned Rails into. We\u2019ll also pass the --edge<\/code> directive:<\/p>\n

    bundle exec railties\/exe\/rails new <parent-folder-path>\/api_app_name --api --edge<\/pre>\n
    Because we\u2019re installing Rails in edge<\/code> mode, it will install a few gems into the Gemfile that we don\u2019t actually need. These are sprockets-rails<\/code>, sprockets<\/code>, and sass-rails<\/code>. Leave them for now because --edge<\/code> Rails seems to need them.<\/p>\n
    Once Rails 5 officially launches, we\u2019ll simply need to run the rails new --api<\/code> command, and it won\u2019t come with these \u201cview\u201d related gems.<\/p>\n
    What makes API mode different?<\/h3>\n
    For the most part, what the API mode does is remove functionality that you don\u2019t actually need when building an API. This includes things like sessions, cookies, assets, and really anything related to making Rails work with a browser. It will also change the generators so that it won\u2019t generate views, helpers, and assets when generating a new resource.<\/p>\n
    Specifically, when running rake middleware<\/code> on both an \u2013api app and a normal app, the normal app includes the following middleware that the API doesn\u2019t:<\/p>\n
    use #<ActiveSupport::Cache::Strategy::LocalCache::Middleware:0x007fa7511b02b0>\r\nuse Rack::MethodOverride\r\nuse WebConsole::Middleware\r\nuse ActionDispatch::Cookies\r\nuse ActionDispatch::Session::CookieStore\r\nuse ActionDispatch::Flash<\/pre>\n
    The difference can also be seen when you compare the ApplicationController<\/code> on a web app versus an API app. The web version extends from ActionController::Base<\/code>, whereas the API version extends from ActionController::API<\/code>, which includes a much smaller subset of functionality.<\/p>\n
    The web ApplicationController:<\/p>\n
    class ApplicationController < ActionController::Base\r\n  # Prevent CSRF attacks by raising an exception.\r\n  # For APIs, you may want to use :null_session instead.\r\n  protect_from_forgery with: :exception\r\nend<\/pre>\n
    The API ApplicationController:<\/p>\n
    class ApplicationController < ActionController::API\r\nend<\/pre>\n
    Let\u2019s generate some scaffolding for a RentalUnit<\/code> model with the following command:<\/p>\n
    bin\/rails g scaffold rental_unit address rooms:integer bathrooms:integer price_cents:integer<\/pre>\n
    If we look at the folders and files that got created, we\u2019ll notice that it hasn\u2019t included any of the normal view files that get created when you generate scaffolding in a normal Rails app.<\/p>\n
    invoke  active_record\r\ncreate    db\/migrate\/20150906194623_create_rental_units.rb\r\ncreate    app\/models\/rental_unit.rb\r\ninvoke    test_unit\r\ncreate      test\/models\/rental_unit_test.rb\r\ncreate      test\/fixtures\/rental_units.yml\r\ninvoke  resource_route\r\n route    resources :rental_units\r\ncreate  app\/serializers\/rental_unit_serializer.rb\r\ninvoke  scaffold_controller\r\ncreate    app\/controllers\/rental_units_controller.rb\r\ninvoke    test_unit\r\ncreate      test\/controllers\/rental_units_controller_test.rb<\/pre>\n
    Responding with JSON<\/h2>\n
    It\u2019s possible that you want to respond with XML, but it\u2019s a fairly safe assumption that you\u2019re going to be responding with JSON. This is where Rails API shines. Before we get to how to respond easily with JSON, let\u2019s talk about which format our JSON should be in.<\/p>\n
    JSON formats<\/h3>\n
    Should we include a root node when responding with multiple objects? What about with single objects? Where do we put meta information, and how do we embed nested or related data?<\/p>\n
    There are a ton of other questions like these that you can ask (and argue about) when trying to decide how the JSON should look but, luckily, there are standards you can follow. json:api<\/a>, popularized by the Ember (and Rails) community, seems to be winning the battle right now and can serve as an anti-bikeshedding<\/a> tool.<\/p>\n
    The JSON serializer we\u2019ll be using in these examples allows us to easily respond in this format.<\/p>\n
    Serializing our JSON responses<\/h3>\n
    ActiveModel::Serializer<\/a> is included by default in your Gemfile when you create an application using the --api<\/code> directive.<\/p>\n
    ActiveModel::Serializer allows you to define which attributes and relationships you would like to include in your JSON response. It also acts as a presenter where you can define custom methods to display extra information or override how it\u2019s displayed in your JSON.<\/p>\n
    The data we\u2019re working with for this article has two models: a RentalUnit and a User, where the RentalUnit belongs to a User, and the User has many Rental Units.<\/p>\n
    In our RentalUnit serializer, we define which attributes to include in the response. Attributes can be anything that the RentalUnit object responds to. price<\/code> and price_per_room<\/code> aren\u2019t real attributes but are methods that we\u2019ve defined in the model. Here we can also say that we want to include the User data along with the RentalUnit by using the belongs_to<\/code> method, much like in Active Record.<\/p>\n
    class RentalUnitSerializer < ActiveModel::Serializer\r\n  attributes :id, :address, :rooms, :bathrooms, :price, :price_per_room\r\n  belongs_to :user\r\nend<\/pre>\n
    In our User serializer, we\u2019ll actually override how the name<\/code> field is displayed in the JSON response. For the sake of privacy, we don\u2019t want to include the full name and are only going to include the first initial followed by their last name. This simple example will fail for Prince, Madonna, and other single-name celebrities, but it\u2019ll do for now. We have access to the object<\/code> which is whatever object you are currently serializing.<\/p>\n
    class UserSerializer < ActiveModel::Serializer \r\n  attributes :id, :name, :email\r\n\r\n  def name \r\n    names = object.name.split(\" \") \r\n    \"#{names[0].first}. #{names[1][1]}\" \r\n  end \r\nend<\/pre>\n
    If we make a request to \/rental_units\/1<\/code>, we\u2019ll get a JSON response like this:<\/p>\n
    {\"id\":1,\"address\":\"460 Jane St.\",\"rooms\":2,\"bathrooms\":2,\"price\":900.0,\"price_per_room\":450.0,\"user\":{\"id\":1,\"name\":\"A. Serna\",\"email\":\"email1@sample.com\"}}<\/pre>\n
    You\u2019ll notice that by default it isn\u2019t in the json:api format. To change it to this format, we simply have to declare an initializer to tell ActiveModel::Serializer how to serialize the JSON data.<\/p>\n
    # config\/initializers\/active_model_serializer.rb\r\nActiveModel::Serializer.config.adapter = ActiveModel::Serializer::Adapter::JsonApi<\/pre>\n
    If we refresh the page (you may have to restart your Rails server after making this change), you\u2019ll see that the data is now in the json:api format.<\/p>\n
    {\"data\":{\"id\":\"1\",\"type\":\"rental_units\",\"attributes\":{\"address\":\"460 Jane St.\",\"rooms\":2,\"bathrooms\":2,\"price\":900.0,\"price_per_room\":450.0},\"relationships\":{\"user\":{\"data\":{\"type\":\"users\",\"id\":\"1\"}}}}}<\/pre>\n
    Caching<\/h2>\n
    Caching is important when dealing with APIs, especially if your API is read-heavy, the data doesn\u2019t change very often, or the responses are slow to generate.<\/p>\n
    If the accuracy of your data doesn\u2019t need to be perfect \u2014 meaning you can afford to serve data that\u2019s a few seconds out of date (or when your data doesn\u2019t change much after its creation) \u2014 one of the best ways to speed up your site is to avoid a request hitting your Rails application at all. Using something like Varnish Cache<\/a>, a reverse proxy<\/a> server can serve cached versions of your content based on different TTLs<\/a>. The fastest work is the work that doesn\u2019t need to be done.<\/p>\n
    With ActiveModel::Serializer (AMS), you get full-object caching and fragment caching. These types of caching will not save you time making SQL queries but will save you time if serializing your objects is a time-consuming process. Things that can make it time consuming include objects that have a ton of fields to serialize or if certain fields are costly to generate. Hitting the database is still required because normally cache expiration is done based on the database ID of the object as well as its updated_at field. This can of course be overridden, but I\u2019ve found that it is generally the best approach.<\/p>\n
    Implementing caching<\/h3>\n
    To use caching with AMS, you\u2019ll first need to decide what cache store your Rails application will use. Popular choices are Memcached<\/a> or Redis<\/a>. For this example, we\u2019ll be using Memcached.<\/p>\n
    The first step is to set which cache store we\u2019ll be using. Next, we\u2019ll turn on caching in the development environment so that we can see its results. This is done in the config\/environments\/development.rb file. Be careful where you put it because in development mode, Rails includes code in this file to disable caching. We\u2019re going to override this so that we can test it out locally. Alternatively, you could launch your site locally in production<\/code> mode.<\/p>\n
    # config\/environments\/development.rb\r\nconfig.cache_store = :mem_cache_store, \"localhost\" config.action_controller.perform_caching = true<\/pre>\n
    You\u2019ll also need to include the dalli<\/code> gem to your Gemfile which is used to talk to Memcached.<\/p>\n
    gem 'dalli', '~> 2.7.4'<\/pre>\n
    The last step is to tell our serializer what to cache. To our rental_unit_serializer.rb file, we\u2019ll add the following line:<\/p>\n
    class RentalUnitSerializer < ActiveModel::Serializer\r\n  cache key: 'rental_unit'\r\n  attributes :id, :address, :rooms, :bathrooms, :price, :price_per_room\r\n  belongs_to :user\r\nend<\/pre>\n
    This will end up caching the entire serialization of the object. For fragment caching, you can pass the options only<\/code> or except<\/code> to have more fine-grained control over what is cached and what isn\u2019t.<\/p>\n
    By making these changes, we\u2019ve changed our response time from 30ms to 50ms\u2026 wait, what? Yes, you heard me right. By adding cache, responses in my application have actually slowed down.<\/p>\n
    Caching quagmires<\/h3>\n
    I\u2019ll be honest that this wasn\u2019t the result I was expecting. The whole reason you add cache to your application is to speed up response time, not slow it down. So I did two things: I reached out to one of the core contributors (and the person who worked on caching) of AMS and asked what his opinion was, and I also broke out some flame graphs to see what was happening inside of my application.<\/p>\n
    Because the application I am testing with isn\u2019t exactly \u201creal-world\u201d (there are only about six fields that I am serializing), it seems faster to actually just regenerate the JSON rather than to go and fetch the cached version of the response.<\/p>\n
    By looking at the flame graph with caching turned on, I could tell that 48 percent of the time was spent in the cache_check<\/code> method or farther down in the stack trace. This seems to account for the slowdown from 30ms to 50ms.<\/p>\n
    active_model_serializers-258f116c3cf5\/lib\/active_model\/serializer\/adapter.rb:110:in `cache_check'   (48 samples - 48.00%)<\/pre>\n
    Here\u2019s an image of the flamegraph, which was produced by using rack mini profiler<\/a> gem with the flamegraph<\/a> gem. I\u2019ve highlighted in black the portion that\u2019s dealing with the cache.<\/p>\n
    \"Flame-graph-with-cache-with-box\"<\/a><\/p>\n
    Support for Russian Doll caching<\/h3>\n
    At the moment Russian Doll caching<\/a> isn\u2019t supported with AMS. There is good news, though! Jo\u00e3o Moura wrote about the current state and future of AMS<\/a> and mentioned that Russian Doll caching is planned. He\u2019s hopeful that it will be ready before Rails 5 is released.<\/p>\n
    Another option if you would like to use Russian Doll caching now is to forgo using AMS and use Jbuilder<\/a> to generate your JSON responses. Jbuilder supports Russian Doll caching, although if you want to also respond using the json:api format, you\u2019ll have to craft the correctly formatted response yourself.<\/p>\n
    Rate Limiting \/ Throttling<\/h2>\n
    One important thing to think about when you have an API is to be able to limit the amount of requests that can be made. This is important either to be able to stop abuse or perhaps based on the amount of access that your users have paid for (free users get fewer requests per hour than paid users).<\/p>\n
    Middleware to the rescue<\/h3>\n
    To help us with rate limiting, we\u2019ll turn to Rack middleware<\/a>. Middleware is essentially how Rails (and other web frameworks) hook into Rack. The request flows through a stack of middleware objects calling call<\/code> on each one, passing the request along, allowing each middleware to either modify it and call the next middleware in the stack, or to halt the request by returning a response.<\/p>\n
    The middleware we will be using will be slotted into the middleware stack before we get to the main Rails middleware. It will allow us to look at the request, determine if we will allow it to continue to our API and be processed normally, or if we want to deny the request because the user has reached their allowed limit.<\/p>\n
    Rack::Attack<\/h3>\n
    Rack::Attack<\/a> is a gem released by Kickstarter to help throttle website (or API) usage. It is middleware that allows us to:<\/p>\n