Module: Grape::DSL::RequestResponse

Included in:
API::Instance
Defined in:
lib/grape/dsl/request_response.rb

Instance Method Summary collapse

Instance Method Details

#content_type(key, val) ⇒ Object

Specify additional content-types, e.g.:

content_type :xls, 'application/vnd.ms-excel'



59
60
61
 
# File 'lib/grape/dsl/request_response.rb', line 59

def content_type(key, val)
  inheritable_setting.namespace_stackable[:content_types] = { key.to_sym => val }
end

#content_types ⇒ Object

All available content types.



64
65
66
67
 
# File 'lib/grape/dsl/request_response.rb', line 64

def content_types
  c_types = inheritable_setting.namespace_stackable_with_hash(:content_types)
  Grape::ContentTypes.content_types_for c_types
end

#default_error_formatter(new_formatter_name = nil) ⇒ Object

Specify a default error formatter.



40
41
42
43
44
45
 
# File 'lib/grape/dsl/request_response.rb', line 40

def default_error_formatter(new_formatter_name = nil)
  return inheritable_setting.namespace_inheritable[:default_error_formatter] if new_formatter_name.nil?

  new_formatter = Grape::ErrorFormatter.formatter_for(new_formatter_name)
  inheritable_setting.namespace_inheritable[:default_error_formatter] = new_formatter
end

#default_error_status(new_status = nil) ⇒ Object

Specify the default status code for errors.



70
71
72
73
74
 
# File 'lib/grape/dsl/request_response.rb', line 70

def default_error_status(new_status = nil)
  return inheritable_setting.namespace_inheritable[:default_error_status] if new_status.nil?

  inheritable_setting.namespace_inheritable[:default_error_status] = new_status
end

#default_format(new_format = nil) ⇒ Object

Specify the default format for the API’s serializers. May be :json or :txt (default).



8
9
10
11
12
 
# File 'lib/grape/dsl/request_response.rb', line 8

def default_format(new_format = nil)
  return inheritable_setting.namespace_inheritable[:default_format] if new_format.nil?

  inheritable_setting.namespace_inheritable[:default_format] = new_format.to_sym
end

#error_formatter(format, options) ⇒ Object 



47
48
49
50
51
52
53
54
55
 
# File 'lib/grape/dsl/request_response.rb', line 47

def error_formatter(format, options)
  formatter = if options.is_a?(Hash) && options.key?(:with)
                options[:with]
              else
                options
              end

  inheritable_setting.namespace_stackable[:error_formatters] = { format.to_sym => formatter }
end

#format(new_format = nil) ⇒ Object

Specify the format for the API’s serializers. May be :json, :xml, :txt, etc.

Raises:



16
17
18
19
20
21
22
23
24
25
26
27
 
# File 'lib/grape/dsl/request_response.rb', line 16

def format(new_format = nil)
  return inheritable_setting.namespace_inheritable[:format] if new_format.nil?

  symbolic_new_format = new_format.to_sym
  inheritable_setting.namespace_inheritable[:format] = symbolic_new_format
  inheritable_setting.namespace_inheritable[:default_error_formatter] = Grape::ErrorFormatter.formatter_for(symbolic_new_format)

  content_type = content_types[symbolic_new_format]
  raise Grape::Exceptions::MissingMimeType.new(new_format) unless content_type

  inheritable_setting.namespace_stackable[:content_types] = { symbolic_new_format => content_type }
end

#formatter(content_type, new_formatter) ⇒ Object

Specify a custom formatter for a content-type.



30
31
32
 
# File 'lib/grape/dsl/request_response.rb', line 30

def formatter(content_type, new_formatter)
  inheritable_setting.namespace_stackable[:formatters] = { content_type.to_sym => new_formatter }
end

#parser(content_type, new_parser) ⇒ Object

Specify a custom parser for a content-type.



35
36
37
 
# File 'lib/grape/dsl/request_response.rb', line 35

def parser(content_type, new_parser)
  inheritable_setting.namespace_stackable[:parsers] = { content_type.to_sym => new_parser }
end

#represent(model_class, options) ⇒ Object

Allows you to specify a default representation entity for a class. This allows you to map your models to their respective entities once and then simply call present with the model.

Note that Grape will automatically go up the class ancestry to try to find a representing entity, so if you, for example, define an entity to represent Object then all presented objects will bubble up and utilize the entity provided on that represent call.

Examples:

class ExampleAPI < Grape::API
  represent User, with: Entity::User

  get '/me' do
    present current_user # with: Entity::User is assumed
  end
end

Parameters:

  • model_class (Class) —

    The model class that will be represented.

  • options (Hash) —

    a customizable set of options

Options Hash (options):

  • :with (Class) —

    The entity class that will represent the model.

Raises:



149
150
151
152
153
 
# File 'lib/grape/dsl/request_response.rb', line 149

def represent(model_class, options)
  raise Grape::Exceptions::InvalidWithOptionForRepresent.new unless options[:with].is_a?(Class)

  inheritable_setting.namespace_stackable[:representations] = { model_class => options[:with] }
end

#rescue_from(*exception_classes, **options) ⇒ Object

Allows you to rescue certain exceptions that occur to return a grape error rather than raising all the way to the server level.

Examples:

Rescue from custom exceptions

class ExampleAPI < Grape::API
  class CustomError < StandardError; end

  rescue_from CustomError
end

Parameters:

  • exception_classes (Array) —

    A list of classes that you want to rescue, or the symbol :all to rescue from all exceptions.

  • block (Block) —

    Execution block to handle the given exception.

  • options (Hash) —

    Options for the rescue usage.

  • handler (Proc) —

    Execution proc to handle the given exception as an alternative to passing a block.

Options Hash (**options):

  • :backtrace (Boolean) —

    Include a backtrace in the rescue response.

  • :rescue_subclasses (Boolean) —

    Also rescue subclasses of exception classes

Raises:

  • (ArgumentError) 


96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
 
# File 'lib/grape/dsl/request_response.rb', line 96

def rescue_from(*args, **options, &block)
  if args.last.is_a?(Proc)
    handler = args.pop
  elsif block
    handler = block
  end

  raise ArgumentError, 'both :with option and block cannot be passed' if block && options.key?(:with)

  handler ||= extract_with(options)

  if args.include?(:all)
    inheritable_setting.namespace_inheritable[:rescue_all] = true
    inheritable_setting.namespace_inheritable[:all_rescue_handler] = handler
  elsif args.include?(:grape_exceptions)
    inheritable_setting.namespace_inheritable[:rescue_all] = true
    inheritable_setting.namespace_inheritable[:rescue_grape_exceptions] = true
    inheritable_setting.namespace_inheritable[:grape_exceptions_rescue_handler] = handler
  else
    handler_type =
      case options[:rescue_subclasses]
      when nil, true
        :rescue_handlers
      else
        :base_only_rescue_handlers
      end

    inheritable_setting.namespace_reverse_stackable[handler_type] = args.to_h { |arg| [arg, handler] }
  end

  inheritable_setting.namespace_stackable[:rescue_options] = options
end