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 http://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: 'http://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 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:
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: 'http://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!
No comments:
Post a Comment