Crafting APIs With Rails

Nowadays it is a common practice to rely heavily on APIs (application programming interfaces). Not only big services like Facebook and Twitter employ them—APIs are very popular due to the spread of client-side frameworks like React, Angular, and many others. Ruby on Rails is following this trend, and the latest version presents a new feature allowing you to create API-only applications. 

Initially this functionality was packed into a separate gem called rails-api, but since the release of Rails 5, it is now part of the framework's core. This feature along with ActionCable was probably the most anticipated, and so today we are going to discuss it.

This article covers how to create API-only Rails applications and explains how to structure your routes and controllers, respond with the JSON format, add serializers, and set up CORS (Cross-Origin Resource Sharing). You will also learn about some options to secure the API and protect it from abuse.

The source for this article is available at GitHub.

Creating an API-Only Application

To start off, run the following command:

rails new RailsApiDemo --api

It is going to create a new API-only Rails application called RailsApiDemo. Don't forget that the support for the --api option was added only in Rails 5, so make sure you have this or a newer version installed.

Open the Gemfile and note that it is much smaller than usual: gems like coffee-rails, turbolinks, and sass-rails are gone.

The config/application.rb file contains a new line:

config.api_only = true

It means that Rails is going to load a smaller set of middleware: for instance, there's no cookies and sessions support. Moreover, if you try to generate a scaffold, views and assets won't be created. Actually, if you check the views/layouts directory, you'll note that the application.html.erb file is missing as well.

Another important difference is that the ApplicationController inherits from the ActionController::API, not ActionController::Base.

That's pretty much it—all in all, this is a basic Rails application you've seen many times. Now let's add a couple of models so that we have something to work with:

rails g model User name:string
rails g model Post title:string body:text user:belongs_to
rails db:migrate

Nothing fancy is going on here: a post with a title, and a body belongs to a user.

Ensure that the proper associations are set up and also provide some simple validation checks:

models/user.rb

  has_many :posts

  validates :name, presence: true

models/post.rb

  belongs_to :user

  validates :title, presence: true
  validates :body, presence: true

Brilliant! The next step is to load a couple of sample records into the newly created tables.

Loading Demo Data

The easiest way to load some data is by utilizing the seeds.rb file inside the db directory. However, I am lazy (as many programmers are) and don't want to think of any sample content. Therefore, why don't we take advantage of the faker gem that can produce random data of various kinds: names, emails, hipster words, "lorem ipsum" texts, and much more.

Gemfile

group :development do
    gem 'faker'
end

Install the gem:

bundle install

Now tweak the seeds.rb:

db/seeds.rb

5.times do
  user = User.create({name: Faker::Name.name})
  user.posts.create({title: Faker::Book.title, body: Faker::Lorem.sentence})
end

Lastly, load your data:

rails db:seed

Responding With JSON

Now, of course, we need some routes and controllers to craft our API. It's a common practice to nest the API's routes under the api/ path. Also, developers usually provide the API's version in the path, for example api/v1/. Later, if some breaking changes have to be introduced, you can simply create a new namespace (v2) and a separate controller.

Here is how your routes can look:

config/routes.rb

namespace 'api' do
    namespace 'v1' do
      resources :posts
      resources :users
    end
end

This generates routes like:

api_v1_posts GET    /api/v1/posts(.:format)     api/v1/posts#index
             POST   /api/v1/posts(.:format)     api/v1/posts#create
 api_v1_post GET    /api/v1/posts/:id(.:format) api/v1/posts#show

You may use a scope method instead of the namespace, but then by default it will look for the UsersController and PostsController inside the controllers directory, not inside the controllers/api/v1, so be careful.

Create the api folder with the nested directory v1 inside the controllers. Populate it with your controllers:

controllers/api/v1/users_controller.rb

module Api
    module V1
        class UsersController < ApplicationController
        end
    end
end

controllers/api/v1/posts_controller.rb

module Api
    module V1
        class PostsController < ApplicationController
        end
    end
end

Note that not only do you have to nest the controller's file under the api/v1 path, but the class itself also has to be namespaced inside the Api and V1 modules.

The next question is how to properly respond with the JSON-formatted data? In this article we will try these solutions: the jBuilder and active_model_serializers gems. So before proceeding to the next section, drop them into the Gemfile:

Gemfile

gem 'jbuilder', '~> 2.5'
gem 'active_model_serializers', '~> 0.10.0'

Then run:

bundle install

Using the jBuilder Gem

jBuilder is a popular gem maintained by the Rails team that provides a simple DSL (domain-specific language) allowing you to define JSON structures in your views.

Suppose we wanted to display all the posts when a user hits the index action:

controllers/api/v1/posts_controller.rb

 def index
    @posts = Post.order('created_at DESC')
end

All you need to do is create the view named after the corresponding action with the .json.jbuilder extension. Note that the view must be placed under the api/v1 path as well:

views/api/v1/posts/index.json.jbuilder

json.array! @posts do |post|
  json.id post.id
  json.title post.title
  json.body post.body
end

json.array! traverses the @posts array. json.id, json.title and json.body generate the keys with the corresponding names setting the arguments as the values. If you navigate to https://localhost:3000/api/v1/posts.json, you'll see an output similar to this one:

[
    {"id": 1, "title": "Title 1", "body": "Body 1"},
    {"id": 2, "title": "Title 2", "body": "Body 2"}
]

What if we wanted to display the author for each post as well? It's simple:

json.array! @posts do |post|
  json.id post.id
  json.title post.title
  json.body post.body
  json.user do
    json.id post.user.id
    json.name post.user.name
  end
end

The output will change to:

[
    {"id": 1, "title": "Title 1", "body": "Body 1", "user": {"id": 1, "name": "Username"}}
]

The contents of the .jbuilder files is plain Ruby code, so you may utilize all the basic operations as usual.

Note that jBuilder supports partials just like any ordinary Rails view, so you may also say: 

json.partial! partial: 'posts/post', collection: @posts, as: :post

and then create the views/api/v1/posts/_post.json.jbuilder file with the following contents:

json.id post.id
json.title post.title
json.body post.body
json.user do
    json.id post.user.id
    json.name post.user.name
end

So, as you see, jBuilder is easy and convenient. However, as an alternative, you may stick with the serializers, so let's discuss them in the next section.

Using Serializers

The rails_model_serializers gem was created by a team who initially managed the rails-api. As stated in the documentation, rails_model_serializers brings convention over configuration to your JSON generation. Basically, you define which fields should be used upon serialization (that is, JSON generation).

Here is our first serializer:

serializers/post_serializer.rb

class PostSerializer < ActiveModel::Serializer
  attributes :id, :title, :body
end

Here we say that all these fields should be present in the resulting JSON. Now methods like to_json and as_json called upon a post will use this configuration and return the proper content.

In order to see it in action, modify the index action like this:

controllers/api/v1/posts_controller.rb

def index
    @posts = Post.order('created_at DESC')
    
    render json: @posts
end

as_json will automatically be called upon the @posts object.

What about the users? Serializers allow you to indicate relations, just like models do. What's more, serializers can be nested:

serializers/post_serializer.rb

class PostSerializer < ActiveModel::Serializer
  attributes :id, :title, :body
  belongs_to :user

  class UserSerializer < ActiveModel::Serializer
    attributes :id, :name
  end
end

Now when you serialize the post, it will automatically contain the nested user key with its id and name. If later you create a separate serializer for the user with the :id attribute excluded:

serializers/post_serializer.rb

class UserSerializer < ActiveModel::Serializer
    attributes :name
end

then @user.as_json won't return the user's id. Still, @post.as_json will return both the user's name and id, so bear it in mind.

Securing the API

In many cases, we don't want anyone to just perform any action using the API. So let's present a simple security check and force our users to send their tokens when creating and deleting posts.

The token will have an unlimited life span and be created upon the user's registration. First of all, add a new token column to the users table:

rails g migration add_token_to_users token:string:index

This index should guarantee uniqueness as there can't be two users with the same token:

db/migrate/xyz_add_token_to_users.rb

add_index :users, :token, unique: true

Apply the migration:

rails db:migrate

Now add the before_save callback:

models/user.rb

before_create -> {self.token = generate_token}

The generate_token private method will create a token in an endless cycle and check whether it is unique or not. As soon as a unique token is found, return it:

models/user.rb

private

def generate_token
    loop do
      token = SecureRandom.hex
      return token unless User.exists?({token: token})
    end
end

You may use another algorithm to generate the token, for example based on the MD5 hash of the user's name and some salt.

User Registration

Of course, we also need to allow users to register, because otherwise they won't be able to obtain their token. I don't want to introduce any HTML views into our application, so instead let's add a new API method:

controllers/api/v1/users_controller.rb

def create
    @user = User.new(user_params)
    if @user.save
      render status: :created
    else
      render json: @user.errors, status: :unprocessable_entity
    end
end

private

def user_params
    params.require(:user).permit(:name)
end

It's a good idea to return meaningful HTTP status codes so that developers understand exactly what is going on. Now you may either provide a new serializer for the users or stick with a .json.jbuilder file. I prefer the latter variant (that's why I do not pass the :json option to the render method), but you are free to choose any of them. Note, however, that the token must not be always serialized, for example when you return a list of all users—it should be kept safe!

views/api/v1/users/create.json.jbuilder

json.id @user.id
json.name @user.name
json.token @user.token

The next step is to test if everything is working properly. You may either use the curl command or write some Ruby code. Since this article is about Ruby, I'll go with the coding option.

Testing User's Registration

To perform an HTTP request, we will employ the Faraday gem, which provides a common interface over many
adapters (the default is Net::HTTP). Create a separate Ruby file, include Faraday, and set up the client:

api_client.rb

require 'faraday'

client = Faraday.new(url: 'https://localhost:3000') do |config|
  config.adapter  Faraday.default_adapter
end

response = client.post do |req|
  req.url '/api/v1/users'
  req.headers['Content-Type'] = 'application/json'
  req.body = '{ "user": {"name": "test user"} }'
end

All these options are pretty self-explanatory: we choose the default adapter, set the request URL to https://localhost:300/api/v1/users, change the content type to application/json, and provide the body of our request.

The server's response is going to contain JSON, so to parse it I'll use the Oj gem:

api_client.rb

require 'oj'

# client here...

puts Oj.load(response.body)
puts response.status

Apart from the parsed response, I also display the status code for debugging purposes.

Now you can simply run this script:

ruby api_client.rb

and store the received token somewhere—we'll use it in the next section.

Authenticating With the Token

To enforce the token authentication, the authenticate_or_request_with_http_token method can be used. It is a part of the ActionController::HttpAuthentication::Token::ControllerMethods module, so don't forget to include it:

controllers/api/v1/posts_controller.rb 

class PostsController < ApplicationController
    include ActionController::HttpAuthentication::Token::ControllerMethods
    # ...
end

Add a new before_action and the corresponding method:

controllers/api/v1/posts_controller.rb 

before_action :authenticate, only: [:create, :destroy]

# ...

private

# ...

def authenticate
    authenticate_or_request_with_http_token do |token, options|
      @user = User.find_by(token: token)
    end
end

Now if the token is not set or if a user with such token cannot be found, a 401 error will be returned, halting the action from executing.

Do note that the communication between the client and the server has to be made over HTTPS, because otherwise the tokens may be easily spoofed. Of course, the provided solution is not ideal, and in many cases it is preferable to employ the OAuth 2 protocol for authentication. There are at least two gems that greatly simplify the process of supporting this feature: Doorkeeper and oPRO.

Creating a Post

To see our authentication in action, add the create action to the PostsController:

controllers/api/v1/posts_controller.rb 

def create
    @post = @user.posts.new(post_params)
    if @post.save
        render json: @post, status: :created
    else
        render json: @post.errors, status: :unprocessable_entity
    end
end

We take advantage of the serializer here to display the proper JSON. The @user was already set inside the before_action.

Now test everything out using this simple code:

api_client.rb

client = Faraday.new(url: 'https://localhost:3000') do |config|
  config.adapter  Faraday.default_adapter
  config.token_auth('127a74dbec6f156401b236d6cb32db0d')
end

response = client.post do |req|
  req.url '/api/v1/posts'
  req.headers['Content-Type'] = 'application/json'
  req.body = '{ "post": {"title": "Title", "body": "Text"} }'
end

Replace the argument passed to the token_auth with the token received upon registration, and run the script.

ruby api_client.rb

Deleting a Post

Deletion of a post is done in the same way. Add the destroy action:

controllers/api/v1/posts_controller.rb 

def destroy
    @post = @user.posts.find_by(params[:id])
    if @post
      @post.destroy
    else
      render json: {post: "not found"}, status: :not_found
    end
end

We only allow users to destroy the posts they actually own. If the post is removed successfully, the 204 status code (no content) will be returned. Alternatively, you may respond with the post's id that was deleted as it will still be available from the memory.

Here is the piece of code to test this new feature:

api_client.rb

response = client.delete do |req|
  req.url '/api/v1/posts/6'
  req.headers['Content-Type'] = 'application/json'
end

Replace the post's id with a number that works for you.

Setting Up CORS

If you want to enable other web services to access your API (from the client-side), then CORS (Cross-Origin Resource Sharing) should be properly set up. Basically, CORS allows web applications to send AJAX requests to the third-party services. Luckily, there is a gem called rack-cors that enables us to easily set everything up. Add it into the Gemfile:

Gemfile

gem 'rack-cors'

Install it:

bundle install

And then provide the configuration inside the config/initializers/cors.rb file. Actually, this file is already created for you and contains a usage example. You can also find some pretty detailed documentation on the gem's page.

The following configuration, for example, will allow anyone to access your API using any method:

config/initializers/cors.rb

Rails.application.config.middleware.insert_before 0, Rack::Cors do
  allow do
    origins '*'

    resource '/api/*',
      headers: :any,
      methods: [:get, :post, :put, :patch, :delete, :options, :head]
  end
end

Preventing Abuse

The last thing I am going to mention in this guide is how to protect your API from abuse and denial of service attacks. There is a nice gem called rack-attack (created by people from Kickstarter) that allows you to blacklist or whitelist clients, prevent the flooding of a server with requests, and more.

Drop the gem into Gemfile:

Gemfile

gem 'rack-attack'

Install it:

bundle install

And then provide configuration inside the rack_attack.rb initializer file. The gem's documentation lists all the available options and suggests some use cases. Here is the sample config that restricts anyone except you from accessing the service and limits the maximum number of requests to 5 per second:

config/initializers/rack_attack.rb

class Rack::Attack
  safelist('allow from localhost') do |req|
    # Requests are allowed if the return value is truthy
    '127.0.0.1' == req.ip || '::1' == req.ip
  end

  throttle('req/ip', :limit => 5, :period => 1.second) do |req|
    req.ip
  end
end

Another thing that needs to be done is including RackAttack as a middleware:

config/application.rb

config.middleware.use Rack::Attack

Conclusion

We've come to the end of this article. Hopefully, by now you feel more confident about crafting APIs with Rails! Do note that this is not the only available option—another popular solution that was around for quite some time is the Grape framework, so you may be interested in checking it out as well.

Don't hesitate to post your questions if something seemed unclear to you. I thank you for staying with me, and happy coding!