How to add ActiveAdmin to Rails API only application

How to add ActiveAdmin to Rails API only application #

Recently at work, I was tasked with creating a back office for our application. We decided to opt for a ready-made solution. The top contender was ActiveAdmin, but I also briefly explored other options such as RailsAdmin and Administrate. In the end, ActiveAdmin was ultimately chosen, primarily due to its superior customizability among the three options, which was crucial for our needs.

After this decision, the next step was to integrate it into our project. The only minor hiccup was that we operate within a Rails API-only application, not configured to run a UI. Therefore, this post serves as a brief and easy-to-follow guide on how to add ActiveAdmin to your Rails API-only application.

Prework #

You might want to consider renaming your current ApplicationController. ActiveAdmin uses the ApplicationController as a base for the controllers it generates. So, if you already have some logic implemented for your API in the ApplicationController (or even if you don’t, but want to ensure better code isolation), the first step is to rename it. In my case, I chose to name it ApiController and updated all my controllers that previously inherited from ApplicationController to now inherit from ApiController.

class ApiController < ActionController::Base
  ...
end

class MyExistentController < ApiController
  ...
end

New Dependencies #

You obviously need to add activeadmin to your Gemfile. However, in addition to that, you need to remember to include a few other dependencies.

gem 'activeadmin'
gem 'devise'
gem 'sprockets-rails', '~> 3.0', '>= 3.0.4'
gem "sassc-rails"

Devise is the authentication solution used by ActiveAdmin. Sprockets is resposible for compiling and serving web assets and SassC::Rails will compile the Sass files.

Now, install the new dependencies.

bundle install

You’ll also need to create a manifest.js file.

mkdir -p app/assets/config
touch app/assets/config/manifest.js
echo "{}" > app/assets/config/manifest.js

Middleware Configurations #

You need to add some middleware configurations to your application.rb to make ActiveAdmin really work.

config.middleware.use ActionDispatch::Flash
config.middleware.use Rack::MethodOverride
config.middleware.use ActionDispatch::Cookies
config.middleware.use ActionDispatch::Session::CookieStore, key: "_session", expire_after: 1.week

Some explanations here:

  • ActionDispatch::Flash: configures the use of the Flash middleware in the application. The Flash is a way to persist messages between actions. It is often used to display a message to the user after a redirect.

  • Rack::MethodOverride: is responsible for allowing HTTP methods other than GET and POST to be used in web forms. This would be essential for ActiveAdmin.

  • ActionDispatch::Cookies: this middleware is responsible for handling cookies.

  • ActionDispatch::Session::CookieStore: configures your cookie preferences.

ActiveAdmin Installation #

Now you can initialize ActiveAdmin.

rails generate active_admin:install

The installation command will generate migration files and update your seed.rb, so don’t forget to run:

rails db:migrate
rails db:seed

I also recommend running your tests (assuming you have them!) to ensure everything is in order.

Model Setup #

ActiveAdmin installations creates a default model named AdminUser to manage the back office users. The final configuration step is to add the class method ransackable_attributes to your AdminUser model. ActiveAdmin requires that all model classes to be accessed by it have this it defined. In this method, you need to list all the attributes that can be used as filters for this resource by ActiveAdmin. So now you’re only doing this for AdminUser but it will be necessary also for any other model you add to your back office.

Running #

Now, finally 🎉, you can initialize your application:

rails server

and access http://localhost:3000/admin with the default ActiveAdmin login:

Congratulations! Your back office is up and running!

Explore further customization possibilities in the ActiveAdmin documentation.