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:

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:

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:

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:



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.


Install the gem:

Now tweak the seeds.rb:


Lastly, load your data:

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:


This generates routes like:

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:



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:


Then run:

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:


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:


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

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

The output will change to:

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: 

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

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:


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:


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:


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:


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:

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


Apply the migration:

Now add the before_save callback:


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:


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:


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!


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:


All these options are pretty self-explanatory: we choose the default adapter, set the request URL to http://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:


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

Now you can simply run this script:

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:


Add a new before_action and the corresponding method:


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:


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:


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

Deleting a Post

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


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:


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:


Install it:

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:


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:


Install it:

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:


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



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!



Related Articles