As a Ruby on Rails developer I have built numerous API applications, I thought it will be a good idea to write a series of posts about building API application with Ruby on Rails.
Before you start the reading, please refer to this sample API application which has following technology stack.
Rails v5.2.0 Ruby v2.4.0 MongoDB v3.4.2
In this series of posts I will cover following about API’s
- Introduction to API’s, difference between normal and API only Rails application.
- Documentation and Testing
Brief about API’s
What are API’s?
API’s are nothing but Application Program Interface with set of routines, protocols and tools used for building software application, where consumer requests to the provider with uniform interface and receives the response in requested representation like JSON, HTML etc.
A high level diagram:
But many times you might have heard that the API’s are Restful.
What are Restful API’s?
Restfulness is derived from Representational State Transfer design idiom for web services that embraces a stateless client-server architecture, having a resource that can be Created, Read, Updated or Deleted (CRUD operations). This resource with a URI(Uniform Resource Identifier) is transferred over a Uniform Interface like HTTP with representation (HTML or JSON or XML) whose state keeps on changing.
Lets see how to build API’s with Rails
There are various options for building API’s, traditionally many developers were using gems like grape, rocket_pants or rails with name-spaced controllers and routes but building API’s with grape and rocket_pants gems is a tedious job as these gems have their own DSL.
If you choose rails with custom configurations for API’s, it will ease your job upto certain extent but rails is not built for API’s, As rails carries some unnecessary modules and middleware(s) alongside which are useless for api only application, then what to use? Well a better option which is developed for building api only applications is rails-api gem.
What is rails-api and How its different from Rails?
Rails-api – Rails for API only applications, in simple terms
- Rails API = Rails – Middleware(s)
- Without assets, views and helpers and much more…
You can create API only application after install latest stable rails version with following command
$rails new expense_manager --api
1. A closer look at ApplicationController
class ApplicationController < ActionController::Base ... end
class ApplicationController < ActionController::API ... end
ActionController::API.ancestors - ActionController::Metal.ancestors
ActionController::Base.ancestors - ActionController::Metal.ancestors
To name a few modules it has removed controller modules like ActionView::Layouts, ActionView::Rendering, ActionController::Helpers, ActionController::FormBuilder, ActionController::Flash, ActionController::Cookies etc.
2. Handled set of middleware
config/application.rb you can see the line
config.api_only = true
This line is responsible for removing middlewares that are not necessary for API only applications.
If you run
in normal rails application you will see the following list of middlewares.
And in API only rails application middleware list looks like
From above lists of middlewares its clear that in API only application middlewares related to cache, cookies, session, flash etc. are removed making API application lighter and more suitable for API’s.
We have covered API introduction and key differences between normal and API only rails application. In the next post we will see how to structure and version your API’s, stay tuned.