Rails framework to add RESTful hypermedia API to your application.

Garage provides a simple, Hypermedia friendly RESTful API to your Rails application using its native RESTful routes. Garage provides a descriptive way to serve your ActiveRecord models, as well as plain old Ruby objects as JSON-based resources.

Garage supports OAuth 2 authorizations via Doorkeeper (more extensions to come), and provides resource-based access controls.

In Gemfile:

gem 'garage', github: 'cookpad/garage'

In your Rails model class:

class Employee < ActiveRecord::Base
  include Garage::Representer

  belongs_to :division
  has_many :projects
  property :id
  property :title
  property :first_name
  property :last_name

  property :division, selectable: true
  collection :projects, selectable: true

  link(:division) { division_path(division) }
  link(:projects) { employee_projects_path(self) }

  def self.build_permissions(perms, other, target)
    perms.permits! :read
  end
end

In your controller class:

class EmployeesController < ApplicationController
  include Garage::RestfulActions

  def require_resources
    @resources = Employee.all
  end
end

In config/initializer/garage.rb:

# Optional
Garage::TokenScope.configure do
  register :public, desc: "accessing publicly available data" do
    access :read, Recipe
  end

  register :read_post, desc: "reading blog post" do
    access :read, Post
  end
end

# If you to want use different authentication/authorization logic.
Garage.configuration.strategy = Garage::Strategy::Test

The following authentication strategies are available.

• Garage::Strategy::NoAuthentication - Does not authenticate request and does not verify permission and access on resource operation. For non-public, internal-use Garage application.
• Garage::Strategy::Test - Trust request thoroughly, and build access token from request headers. For testing or prototyping.
• Garage::Strategy::Doorkeeper - Authenticate request with doorkeeper gem. To use this strategy, bundle garage-doorkeeper gem.
• Garage::Strategy::AuthServer - Delegate authentication to OAuth server. This auth strategy has configurations.

To delegate auth to your OAuth server, use Garage::Strategy::AuthServer strategy. Then configure auth server strategy:

• Garage.configuration.auth_server_url - A full url of your OAuth server's access token validation endpoint. i.e. https://example.com/token.
• Garage.configuration.auth_server_host - A host header value to request to your OAuth server. Can be empty.
• Garage.configuration.auth_server_timeout - A read timeout second. Default is 1 second.

The OAuth server must response a json with following structure.

• token(string) - OAuth access token value.
• token_type (string) - OAuth access token value. i.e. bearer type.
• scope (string) - OAuth scopes separated by spaces. i.e. public read_user.
• application_id (integer) - OAuth application id of the access token.
• resource_owner_id (integer, null) - Resource owner id of the access token.
• expired_at (string, null) - Expire datetime with string representation.
• revoked_at (string, null) - Revoked datetime with string representation.

When requested access token is invalid, OAuth server must response 401.

Garage supports customizable Authentication/Authorization strategy. The Strategy has some conventions to follow.

• Offer OAuth access token via access_token method. With no access token case (does not authenticate request) access_token should return nil.
• Register verify_auth hook as before filter in included block if authenticate request. Or register custom authentication hook. The custom authentication hook should response unauthorized using unauthorized_render_options when fails to authenticate a request.
• Offer whether verify permission and access in RestfulActions via verify_permission method. Return true to verify them.

module MyStrategy
  extend ActiveSupport::Concern

  included do
    # Register verify_auth hook if you want to authenticate request.
    before_action :verify_auth
  end

  def access_token
    # Fetch some `attributes` from DB or auth server API using request.
    # Then returns an AccessToken with caching.
    @access_token ||= Garage::Strategy::AccessToken.new(attributes)
  end

  # Whether verify permission and access in `RestfulActions`.
  def verify_permission?
    true
  end
end

• Tatsuhiko Miyagawa
• Taiki Ono
• Yusuke Mito
• Ryo Nakamura

• roar
• doorkeeper