Module: RESTFramework::Mixins::BaseControllerMixin

Included in:

BaseModelControllerMixin

Defined in:

lib/rest_framework/mixins/base_controller_mixin.rb

Overview

This module provides the common functionality for any controller mixins, a ‘root` action, and the ability to route arbitrary actions with `extra_actions`. This is also where `render_api` is implemented.

Defined Under Namespace

Modules: ClassMethods

Constant Summary

RRF_BASE_CONFIG =

{
  extra_actions: nil,
  extra_member_actions: nil,
  singleton_controller: nil,

  # Options related to metadata and display.
  title: nil,
  description: nil,
  inflect_acronyms: ["ID", "IDs", "REST", "API", "APIs"].freeze,

  # Options related to serialization.
  rescue_unknown_format_with: :json,
  serializer_class: nil,
  serialize_to_json: true,
  serialize_to_xml: true,

  # Custom integrations (reduces serializer performance due to method calls).
  enable_action_text: false,
  enable_active_storage: false,
}

RRF_BASE_INSTANCE_CONFIG =

{
  # Options related to pagination.
  paginator_class: nil,
  page_size: 20,
  page_query_param: "page",
  page_size_query_param: "page_size",
  max_page_size: nil,

  # Option to disable serializer adapters by default, mainly introduced because Active Model
  # Serializers will do things like serialize `[]` into `{"":[]}`.
  disable_adapters_by_default: true,
}

Class Method Summary

• .included(base) ⇒ Object

Instance Method Summary

• #api_response(payload, **kwargs) ⇒ Object (also: #render_api)

  Render a browsable API for ‘html` format, along with basic `json`/`xml` formats, and with support or passing custom `kwargs` to the underlying `render` calls.

• #options ⇒ Object
• #options_metadata ⇒ Object
• #root ⇒ Object

  Default action for API root.

• #rrf_error_handler(e) ⇒ Object
• #serialize(data, **kwargs) ⇒ Object

  Serialize the given data using the ‘serializer_class`.

• #serializer_class ⇒ Object

Class Method Details

.included(base) ⇒ Object

# File 'lib/rest_framework/mixins/base_controller_mixin.rb', line 141

def self.included(base)
  return unless base.is_a?(Class)

  base.extend(ClassMethods)

  # By default, the layout should be set to `rest_framework`.
  base.layout("rest_framework")

  # Add class attributes (with defaults) unless they already exist.
  RRF_BASE_CONFIG.each do |a, default|
    next if base.respond_to?(a)

    base.class_attribute(a, default: default, instance_accessor: false)
  end
  RRF_BASE_INSTANCE_CONFIG.each do |a, default|
    next if base.respond_to?(a)

    base.class_attribute(a, default: default)
  end

  # Alias `extra_actions` to `extra_collection_actions`.
  unless base.respond_to?(:extra_collection_actions)
    base.singleton_class.alias_method(:extra_collection_actions, :extra_actions)
    base.singleton_class.alias_method(:extra_collection_actions=, :extra_actions=)
  end

  # Skip CSRF since this is an API.
  begin
    base.skip_before_action(:verify_authenticity_token)
  rescue
    nil
  end

  # Handle some common exceptions.
  unless RESTFramework.config.disable_rescue_from
    base.rescue_from(
      ActionController::ParameterMissing,
      ActionController::UnpermittedParameters,
      ActiveRecord::AssociationTypeMismatch,
      ActiveRecord::NotNullViolation,
      ActiveRecord::RecordNotFound,
      ActiveRecord::RecordInvalid,
      ActiveRecord::RecordNotSaved,
      ActiveRecord::RecordNotDestroyed,
      ActiveRecord::RecordNotUnique,
      ActiveModel::UnknownAttributeError,
      with: :rrf_error_handler,
    )
  end

  # Use `TracePoint` hook to automatically call `rrf_finalize`.
  unless RESTFramework.config.disable_auto_finalize
    # :nocov:
    TracePoint.trace(:end) do |t|
      next if base != t.self

      base.rrf_finalize

      # It's important to disable the trace once we've found the end of the base class definition,
      # for performance.
      t.disable
    end
    # :nocov:
  end
end

Instance Method Details

#api_response(payload, **kwargs) ⇒ Object Also known as: render_api

Render a browsable API for ‘html` format, along with basic `json`/`xml` formats, and with support or passing custom `kwargs` to the underlying `render` calls.

# File 'lib/rest_framework/mixins/base_controller_mixin.rb', line 247

def api_response(payload, **kwargs)
  html_kwargs = kwargs.delete(:html_kwargs) || {}
  json_kwargs = kwargs.delete(:json_kwargs) || {}
  xml_kwargs = kwargs.delete(:xml_kwargs) || {}

  # Raise helpful error if payload is nil. Usually this happens when a record is not found (e.g.,
  # when passing something like `User.find_by(id: some_id)` to `api_response`). The caller should
  # actually be calling `find_by!` to raise ActiveRecord::RecordNotFound and allowing the REST
  # framework to catch this error and return an appropriate error response.
  if payload.nil?
    raise RESTFramework::NilPassedToAPIResponseError
  end

  # If `payload` is an `ActiveRecord::Relation` or `ActiveRecord::Base`, then serialize it.
  if payload.is_a?(ActiveRecord::Base) || payload.is_a?(ActiveRecord::Relation)
    payload = self.serialize(payload)
  end

  # Do not use any adapters by default, if configured.
  if self.disable_adapters_by_default && !kwargs.key?(:adapter)
    kwargs[:adapter] = nil
  end

  # Flag to track if we had to rescue unknown format.
  already_rescued_unknown_format = false

  begin
    respond_to do |format|
      if payload == ""
        format.json { head(kwargs[:status] || :no_content) } if self.class.serialize_to_json
        format.xml { head(kwargs[:status] || :no_content) } if self.class.serialize_to_xml
      else
        format.json {
          render(json: payload, **kwargs.merge(json_kwargs))
        } if self.class.serialize_to_json
        format.xml {
          render(xml: payload, **kwargs.merge(xml_kwargs))
        } if self.class.serialize_to_xml
        # TODO: possibly support more formats here if supported?
      end
      format.html {
        @payload = payload
        if payload == ""
          @json_payload = "" if self.class.serialize_to_json
          @xml_payload = "" if self.class.serialize_to_xml
        else
          @json_payload = payload.to_json if self.class.serialize_to_json
          @xml_payload = payload.to_xml if self.class.serialize_to_xml
        end
        @title ||= self.class.get_title
        @description ||= self.class.description
        @route_props, @route_groups = RESTFramework::Utils.get_routes(
          Rails.application.routes, request
        )
        begin
          render(**kwargs.merge(html_kwargs))
        rescue ActionView::MissingTemplate
          # A view is not required, so just use `html: ""`.
          render(html: "", layout: true, **kwargs.merge(html_kwargs))
        end
      }
    end
  rescue ActionController::UnknownFormat
    if !already_rescued_unknown_format && rescue_format = self.class.rescue_unknown_format_with
      request.format = rescue_format
      already_rescued_unknown_format = true
      retry
    else
      raise
    end
  end
end

#options ⇒ Object

# File 'lib/rest_framework/mixins/base_controller_mixin.rb', line 323

def options
  return api_response(self.options_metadata)
end

#options_metadata ⇒ Object

# File 'lib/rest_framework/mixins/base_controller_mixin.rb', line 223

def options_metadata
  return self.class.options_metadata
end

#root ⇒ Object

Default action for API root.

# File 'lib/rest_framework/mixins/base_controller_mixin.rb', line 39

def root
  render_api({message: "This is the API root."})
end

#rrf_error_handler(e) ⇒ Object

# File 'lib/rest_framework/mixins/base_controller_mixin.rb', line 227

def rrf_error_handler(e)
  status = case e
  when ActiveRecord::RecordNotFound
    404
  else
    400
  end

  return api_response(
    {
      message: e.message,
      errors: e.try(:record).try(:errors),
      exception: RESTFramework.config.show_backtrace ? e.full_message : nil,
    }.compact,
    status: status,
  )
end

#serialize(data, **kwargs) ⇒ Object

Serialize the given data using the ‘serializer_class`.

# File 'lib/rest_framework/mixins/base_controller_mixin.rb', line 217

def serialize(data, **kwargs)
  return RESTFramework::Utils.wrap_ams(self.serializer_class).new(
    data, controller: self, **kwargs
  ).serialize
end

#serializer_class ⇒ Object

# File 'lib/rest_framework/mixins/base_controller_mixin.rb', line 207

def serializer_class
  # TODO: Compatibility; remove in 1.0.
  if klass = self.try(:get_serializer_class)
    return klass
  end

  return self.class.serializer_class
end