module Garage::RestfulActions
Public Instance Methods
Public: Create a new resource Calls `create_resource` in your controller to create a new resource Requires `:write` permission on `resource_class` specified for `@resources`
# File lib/garage/restful_actions.rb, line 71 def create @resource = create_resource respond_with @resource, :location => location end
Public: Delete the resource Calls `destroy_resource` in your controller to destroy `@resource` Requires `:write` permission on `@resource`
# File lib/garage/restful_actions.rb, line 87 def destroy @resource = destroy_resource respond_with @resource, respond_with_resource_options end
Public: List resources Renders `@resources` with options specified with `respond_with_resources_options` Requires `:read` permission on `resource_class` specified for `@resources`
# File lib/garage/restful_actions.rb, line 57 def index respond_with @resources, respond_with_resources_options end
Public: Get the resource Renders `@resource` with options specified with `respond_with_resource_options` Requires `:read` permission on `@resource`
# File lib/garage/restful_actions.rb, line 64 def show respond_with @resource, respond_with_resource_options end
Public: Update the resource Calls `update_resource` in your controller to update `@resource` Requires `:write` permission on `@resource`
# File lib/garage/restful_actions.rb, line 79 def update @resource = update_resource respond_with @resource, respond_with_resource_options end
Private Instance Methods
Override to create a new resource
# File lib/garage/restful_actions.rb, line 206 def create_resource raise NotImplementedError, "#{self.class}#create_resource is not implemented" end
Private: returns either `:read` or `:write`, depending on the current action name
# File lib/garage/restful_actions.rb, line 95 def current_operation if %w[create update destroy].include?(action_name) :write else :read end end
Override to destroy @resource
# File lib/garage/restful_actions.rb, line 216 def destroy_resource raise NotImplementedError, "#{self.class}#destroy_resource is not implemented" end
# File lib/garage/restful_actions.rb, line 230 def location { action: :show, id: @resource.id } if @resource.try(:respond_to?, :id) end
# File lib/garage/restful_actions.rb, line 185 def operated_resource if @operated_resource @operated_resource elsif @resources MetaResource.new(self.class.resource_class) else Garage.configuration.cast_resource.call(@resource) end end
Private: Call this method if you need to change the target resource to provision access and permission.
def require_resources @resources = Post.where(user_id: @user.id) end
By default, in `index` and `create` actions, Garage
will check `:read` and `:write` access respectively on the default `resource_class` of `@resources`, in this case Post class. If you need more fine grained control than that, you should specify the optional parameters here, such as:
def require_resources @resources = Post.where(user_id: @user.id) protect_source_as PrivatePost, user: @user end
This way, the token should require access scope to `PrivatePost` (instead of `Post`), and the authorized user should have a permission to operate the action on resources owned by `@user` (instead of public). The `:user` option will be passed as parameters to `build_permissions` class method.
# File lib/garage/restful_actions.rb, line 178 def protect_resource_as(klass, args = {}) if klass.is_a?(Hash) klass, args = self.class.resource_class, klass end @operated_resource = MetaResource.new(klass, args) end
Private: Call this method to require additional access on extra resource class your controller needs access to. It will check if the current request token has an access permission (scope) to perform the operation (`:read` or `:write`) on the resource class.
Examples
before_action :require_stream def require_stream require_access! PostStream, :read end
# File lib/garage/restful_actions.rb, line 132 def require_access!(resource, operation = nil) operation ||= current_operation ability_from_token.access!(resource.resource_class, operation) end
Private: Call this method to require additional access and permission on extra resource your controller performs operation on.
# File lib/garage/restful_actions.rb, line 140 def require_access_and_permission!(resource, operation = nil) require_permission!(resource, operation) require_access!(resource, operation) end
# File lib/garage/restful_actions.rb, line 145 def require_action_permission_crud if operated_resource require_access_and_permission!(operated_resource, current_operation) else Rails.logger.debug "skipping permissions check since there's no @resource(s) set" end end
Private: Call this method to require additional permission on extra resource your controller handles. It will check if the current request user has permission to perform the operation (`:read` or `:write`) on the resource.
Examples
before_action :require_recipe def require_recipe @recipe = Recipe.find(params[:recipe_id]) require_permission! @recipe, :read end
# File lib/garage/restful_actions.rb, line 115 def require_permission!(resource, operation = nil) operation ||= current_operation resource.authorize!(current_resource_owner, operation) end
Override to set @resource
# File lib/garage/restful_actions.rb, line 196 def require_resource raise NotImplementedError, "#{self.class}#require_resource is not implemented" end
Override to set @resources
# File lib/garage/restful_actions.rb, line 201 def require_resources raise NotImplementedError, "#{self.class}#require_resources is not implemented" end
Override this if you want to pass options to respond_with in show, update and destroy actions
# File lib/garage/restful_actions.rb, line 226 def respond_with_resource_options {} end
Override this if you want to pass options to respond_with in index action
# File lib/garage/restful_actions.rb, line 221 def respond_with_resources_options {} end
Override to update @resource
# File lib/garage/restful_actions.rb, line 211 def update_resource raise NotImplementedError, "#{self.class}#update_resource is not implemented" end