Class: ActionController::API

Inherits:
Metal
  • Object
show all
Extended by:
Compatibility
Includes:
AbstractController::Rendering, HideActions, ActionView::Rendering, StrongParameters
Defined in:
lib/rails-api/action_controller/api.rb

Overview

API Controller is a lightweight version of ActionController::Base, created for applications that don't require all functionality that a complete Rails controller provides, allowing you to create faster controllers for example for API only applications.

An API Controller is different from a normal controller in the sense that by default it doesn't include a number of features that are usually required by browser access only: layouts and templates rendering, cookies, sessions, flash, assets, and so on. This makes the entire controller stack thinner and faster, suitable for API applications. It doesn't mean you won't have such features if you need them: they're all available for you to include in your application, they're just not part of the default API Controller stack.

By default, only the ApplicationController in a Rails application inherits from ActionController::API. All other controllers in turn inherit from ApplicationController.

A sample controller could look like this:

class PostsController < ApplicationController
  def index
    @posts = Post.all
    render json: @posts
  end
end

Request, response and parameters objects all work the exact same way as ActionController::Base.

Renders

The default API Controller stack includes all renderers, which means you can use render :json and brothers freely in your controllers. Keep in mind that templates are not going to be rendered, so you need to ensure your controller is calling either render or redirect in all actions.

def show
  @post = Post.find(params[:id])
  render json: @post
end

Redirects

Redirects are used to move from one action to another. You can use the redirect method in your controllers in the same way as ActionController::Base. For example:

def create
  redirect_to root_url and return if not_authorized?
  # do stuff here
end

Adding new behavior

In some scenarios you may want to add back some functionality provided by ActionController::Base that is not present by default in ActionController::API, for instance MimeResponds. This module gives you the respond_to and respond_with methods. Adding it is quite simple, you just need to include the module in a specific controller or in ApplicationController in case you want it available to your entire app:

class ApplicationController < ActionController::API
  include ActionController::MimeResponds
end

class PostsController < ApplicationController
  respond_to :json, :xml

  def index
    @posts = Post.all
    respond_with @posts
  end
end

Quite straightforward. Make sure to check ActionController::Base available modules if you want to include any other functionality that is not provided by ActionController::API out of the box.

Defined Under Namespace

Modules: Compatibility

Constant Summary collapse

MODULES =
[
  UrlFor,
  Redirecting,
  Rendering,
  Renderers::All,
  ConditionalGet,
  RackDelegation,

  ForceSSL,
  DataStreaming,

  # Before callbacks should also be executed the earliest as possible, so
  # also include them at the bottom.
  AbstractController::Callbacks,

  # Append rescue at the bottom to wrap as much as possible.
  Rescue,

  # Add instrumentations hooks at the bottom, to ensure they instrument
  # all the methods properly.
  Instrumentation
].freeze
DEFAULT_PROTECTED_INSTANCE_VARIABLES =
begin
  if Rails::VERSION::MAJOR == 5 || (Rails::VERSION::MAJOR == 4 && Rails::VERSION::MINOR > 0)
    Set
  else
    Array
  end
end.new

Class Method Summary collapse

Methods included from Compatibility

allow_forgery_protection=, asset_host=, asset_path=, assets_dir=, cache_store, cache_store=, helper, helper_method, helpers_path=, javascripts_dir=, page_cache_directory=, perform_caching=, relative_url_root=, stylesheets_dir=

Class Method Details

.protected_instance_variablesObject


169
170
171
# File 'lib/rails-api/action_controller/api.rb', line 169

def self.protected_instance_variables
  DEFAULT_PROTECTED_INSTANCE_VARIABLES
end

.without_modules(*modules) ⇒ Object

Shortcut helper that returns all the ActionController::API modules except the ones passed in the argument:

class MetalController
  ActionController::API.without_modules(:Redirecting, :DataStreaming).each do |left|
    include left
  end
end

This gives better control over what you want to exclude and makes it easier to create an api controller class, instead of listing the modules required manually.


117
118
119
120
121
122
123
# File 'lib/rails-api/action_controller/api.rb', line 117

def self.without_modules(*modules)
  modules = modules.map do |m|
    m.is_a?(Symbol) ? ActionController.const_get(m) : m
  end

  MODULES - modules
end