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'


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

def content_type(key, val)
  inheritable_setting.add_content_type(key.to_sym, val)
end

#content_types ⇒ Object

All available content types.



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

def content_types
  Grape::ContentTypes.content_types_for(inheritable_setting.content_types)
end

#default_error_formatter(new_formatter_name = nil) ⇒ Object

Specify a default error formatter, by the name it is registered under. A name nothing is registered for used to be stored as ErrorFormatter::Txt — the fallback the lookup applied — so a typo read back as a working setting and silently rendered errors as text.

Raises:



43
44
45
46
47
48
49
50
 
# File 'lib/grape/dsl/request_response.rb', line 43

def default_error_formatter(new_formatter_name = nil)
  return inheritable_setting.default_error_formatter if new_formatter_name.nil?

  formatter = Grape::ErrorFormatter.formatter_for(new_formatter_name)
  raise Grape::Exceptions::UnknownErrorFormatter.new(new_formatter_name) if formatter.nil?

  inheritable_setting.default_error_formatter = formatter
end

#default_error_status(new_status = nil) ⇒ Object

Specify the default status code for errors.



75
76
77
78
79
 
# File 'lib/grape/dsl/request_response.rb', line 75

def default_error_status(new_status = nil)
  return inheritable_setting.default_error_status if new_status.nil?

  inheritable_setting.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.default_format if new_format.nil?

  inheritable_setting.default_format = new_format.to_sym
end

#error_formatter(format, options = nil, with: nil) ⇒ Object

Specify a custom error formatter for a format, passed positionally or as with:. A nil formatter used to be registered as-is, which is the one thing the registration cannot mean: the format then resolves as if the call had never been made. Reject it here, where the mistake is.

Raises:

  • (ArgumentError) 


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

def error_formatter(format, options = nil, with: nil)
  formatter = with || options
  raise ArgumentError, "error_formatter `#{format.inspect}` requires a formatter, given positionally or as `with:`" if formatter.nil?

  inheritable_setting.add_error_formatter(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.format if new_format.nil?

  symbolic_new_format = new_format.to_sym
  inheritable_setting.format = symbolic_new_format
  inheritable_setting.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.add_content_type(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.add_formatter(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.add_parser(content_type.to_sym, new_parser)
end

#represent(model_class, with:) ⇒ 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

Raises:



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

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

  inheritable_setting.add_representation(model_class, with)
end

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

Parameters:

  • exception_classes (Array) —

    A list of classes that you want to rescue, or one of the meta selectors :all, :grape_exceptions, :internal_grape_exceptions. Meta selectors must be used alone; mixing with exception classes raises ArgumentError.

  • block (Block) —

    Execution block to handle the given exception.

  • with (Proc) —

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

  • rescue_subclasses (Boolean) —

    Also rescue subclasses of exception classes; defaults to true.

  • backtrace (Boolean) —

    Include the rescued exception's backtrace in the rescue response body.

  • original_exception (Boolean) —

    Include inspect of the rescued exception in the rescue response body.

Raises:

  • (ArgumentError) 


109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
 
# File 'lib/grape/dsl/request_response.rb', line 109

def rescue_from(*args, with: nil, rescue_subclasses: true, backtrace: false, original_exception: false, &block)
  handler = extract_handler(args, with:, block:)
  meta_selector = (args & META_RESCUE_SELECTORS).first
  raise ArgumentError, "rescue_from `#{meta_selector.inspect}` does not accept additional arguments" if meta_selector && args.size > 1

  case meta_selector
  when :all
    inheritable_setting.add_all_rescue_handler(handler)
  when :grape_exceptions
    inheritable_setting.add_grape_exceptions_rescue_handler(handler)
  when :internal_grape_exceptions
    inheritable_setting.add_internal_grape_exceptions_rescue_handler(handler)
  else
    inheritable_setting.add_rescue_handlers(args.to_h { |klass| [klass, handler] }, subclasses: rescue_subclasses)
  end

  inheritable_setting.add_rescue_options(RescueOptions.new(backtrace:, original_exception:))
end