RailsApiModel

gem 'rails_api_model'

module ApiModels
  class User < RailsApiModel::Base
    # Associate an ActiveRecord model
    active_record_model ::User

    filters do
      # Allow filtering by these fields of the model
      allow_fields :name, :email, :rank, :created_at
    end

    fields do
      # Allow these fields to be displayed in the return object
      allow_fields :name, :email, :rank, :created_at, :updated_at

      # If not specified otherwise, display only these fields
      default_fields :name, :email
    end

    sorts do
      # Allow sorting by these fields
      allow_fields :name, :rank, :created_at
    end
  end
end

class UsersController < ApplicationController
  def index
    # Use the API model to filter, load and return the queried users
    ApiModels::User.query_all(params)
  end
end

module ApiModels
  class User < RailsApiModel::Base
    # Associate an ActiveRecord model
    active_record_model ::User

    filters do
      # Allow filtering by these fields of the model - `api/users?name=John&rank=admin`
      allowed_fields :name, :email, :rank, :created_at

      # Allow scopes to be used - `api/users?scope=admin,facebook`.
      # Using multiple scopes defines an intersection between them.
      allowed_scopes :user, :admin, :facebook

      # You can set custom filters
      filter :register_date do |relation, param_value|
        relation.where 'DATE(created_at) = DATE(?)', param_value
      end

      # Or, preferrably, define a custom filter class in `app/api_models/filters`...
      #
      module ApiModels
        module Filters
          class RegisterDateFilter < RailsApiModels::Filters::Base
            def apply_scope(relation, key, value)
              relation.where 'DATE(created_at) = DATE(?)', param_value
            end
          end
        end
      end
      #
      # ...and use it here:
      #
      filter :register_date, Filters::RegisterDateFilter

      # Set default filter
      default rank: :user

      # This works with all filters that can be used as a URL parameter:
      default 'rank:lt' => 1
      #
      # You sometimes need a block:
      default { {'created_at:lt' => Time.zone.now} }
      #
      # You can default to custom filters as well:
      default { {register_date: Time.zone.now} }

      # You can also filter by fields of an associated model. Let's say you have `has_many :posts`
      # on `User`. If you have defined `ApiModel::Post`
      #
      allowed_associations :posts
      #
      # This enable you to do `api/users?posts.created_at:gt=2015-12-01` which will give you all users
      # who have posted since 2015-12-01. This will only work if you have `allowed_fields :created_at`
      # in `ApiModel::Post`.
    end

    fields do
      # Allow these fields to be displayed in the return object
      allowed_fields :name, :email, :rank, :created_at, :updated_at

      # Set named groups of fields:
      #
      group :basic, [:name, :email]
      group :extended, [:name, :email, :rank]
      group :timestamps, [:created_at, :updated_at]
      #
      # This allows you to conveniently set which fields you want returned:
      #
      #   GET /api/users?fields=basic,timestamps => will give you objects with `name`,
      #                                             `email`, `created_at` and `updated_at`
      #
      # This is how the `_defaults` field works:
      #
      group :_defaults, User.fields.default

      # If not specified otherwise, display only these fields
      default :name, :email

      # You can also display an embedded object for a referenced model:
      #
      allowed_associations :posts, default_group: :basic
      #
      #   GET /api/users?fields=basic,posts => object with `name`, `email` and `posts` array
      #
      # The `default_group` specifies which of the groups defined in `ApiModels::Post`
      # will be used for the embedded object.
      # This can, of course, be overriden in the request:
      #
      #   GET /api/users?fields=basic,posts:extended => the `posts` array will contain the extended posts
    end

    sorts do
      # Allow sorting by these fields
      allowed_fields :name, :rank, :created_at

      # TODO: Describe custom sorts, default sorts, etc.
    end
  end
end