Setting Up an API on an Existing Rails Application

written in api, rails, technical

Hey y’all it’s been a long time! Life has been a bit busy at the moment and I’ll write a blog all about that in the non-technical session ASAP.

Today I’m going to talk about setting up your current Rails application with an API. This is assuming that you have a working Rails application, preferably with data to see in the browser when you have it up and running through the rails server.

The Pre-Coding Code

So before we do any serious setup the first thing we will need to do is access the rails-api gem. To do this put this line inside your Gemfile file

[Gemfile]
1
gem 'rails-api' , require: 'rails-api/action_controller/api'

and bundle install.

Ain’t No Basic Controller

At this point you will have access to the API Action Controller which I suggest you read up on in the Ruby on Rails API docs. So now that your application is ready for API goodness you’ll want to create a sub-folder underneath your app/controllers titled api .

At this point underneath app/controllers you should have your main controllers, ie. application_controller or user_controller, and your api folder.

Now inside this api folder you will want to add an api_controller.rb file and an optional v1 folder.

The api_controller.rb will be your API controller, this is essentially the application controller for your API. Inside your api_controller you will want to set it up similarly to the application_controller

[api_controller.rb]

1
2
  class Api::ApiController < ActionController::API
  end

As you can see we are no longer using the Base Action Controller, instead we’re using the API Action Controller. This will be one of the sub controllers that will inherit from the Base Action Controller. If in the future you want to implement an API sign in option with a username and secret as many api’s have now-a-days this if the file you would do this in.

At this point you should have the api_controller.rb setup and hopefully, but not required, the v1 folder setup.

I suggest implement the v1 folder incase you decide to create multiple versions of the api in the future.

So let’s say you have the v1 setup. Inside this folder you will have all of the controllers you’re find in the main controllers folder. Currently I am using an api user_controller to allow api users to access the users in the system.

Get The Data You Want

Inside the user_controller.rb you will want to set it up depending on which information you want to be shown. Let’s say that your application user_controller has both index and show methods, this will mean your API user_controller will also have index and show methods.

[api/v1/user_controller.rb]
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
  class Api::V1::UserController < Api::ApiController
  include ActionController::MimeResponds
    def index
      respond_to do |format|
        @users = User.all
        format.json { render json:@users }
      end
    end
    def show
      respond_to do |format|
        @user = User.find(params[:id])
        format.json { render json:@user }
      end
    end
  end

Here I have set it up so that when the api user goes to example.com/api/v1/users.json they will see all the users in the database. As you can see I put “.json” at the end of the html address, this is because inside the api user_controller I specified the format I want to respond to. I you wanted the api to respond to an xml call then you would put

[user_controller.rb]
1
  format.xml {render xml:@user}

or even allowing access to both json and xml calls

[user_controller.rb]

1
2
3
    if format.json {render json:@user}
    if format.xml {render xml:@user}

I setup the user.show api call similarly. When an api user calls example.com/api/v1/users/1.json this will show that specific user’s data.

Almost Done

Awesome, you’re almost done. Just like any other controller you will need to set up the routes.

[config/routes.rb]
1
2
3
4
5
6
7
  namespace :api do
    namespace :v1 do
      resources :user do
        resources :other_controllers
      end
    end
  end

I chose to organize my api groups of controllers under a namespace and again under a v1 namespace. This allows me to organize my routes instead of searching for them through the document. Optionally I chose to make my api/user_controller.rb also a namespace. This requires me to access my other api controllers based on the user api controller.

And that’s it! Keep on being badass! <3


Comments