Module: Grape::DSL::RequestResponse::ClassMethods

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'



62
63
64
 
# File 'lib/grape/dsl/request_response.rb', line 62

def content_type(key, val)
  namespace_stackable(:content_types, key.to_sym => val)
end

#content_types ⇒ Object

All available content types.



67
68
69
70
 
# File 'lib/grape/dsl/request_response.rb', line 67

def content_types
  c_types = 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.



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

def default_error_formatter(new_formatter_name = nil)
  return namespace_inheritable(:default_error_formatter) unless new_formatter_name

  new_formatter = Grape::ErrorFormatter.formatter_for(new_formatter_name)
  namespace_inheritable(:default_error_formatter, new_formatter)
end

#default_error_status(new_status = nil) ⇒ Object

Specify the default status code for errors.



73
74
75
 
# File 'lib/grape/dsl/request_response.rb', line 73

def default_error_status(new_status = nil)
  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).



13
14
15
 
# File 'lib/grape/dsl/request_response.rb', line 13

def default_format(new_format = nil)
  namespace_inheritable(:default_format, new_format.nil? ? nil : new_format.to_sym)
end

#error_formatter(format, options) ⇒ Object 



50
51
52
53
54
55
56
57
58
 
# File 'lib/grape/dsl/request_response.rb', line 50

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

  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:



19
20
21
22
23
24
25
26
27
28
29
30
 
# File 'lib/grape/dsl/request_response.rb', line 19

def format(new_format = nil)
  return namespace_inheritable(:format) unless new_format

  symbolic_new_format = new_format.to_sym
  namespace_inheritable(:format, symbolic_new_format)
  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

  namespace_stackable(:content_types, symbolic_new_format => content_type)
end

#formatter(content_type, new_formatter) ⇒ Object

Specify a custom formatter for a content-type.



33
34
35
 
# File 'lib/grape/dsl/request_response.rb', line 33

def formatter(content_type, new_formatter)
  namespace_stackable(:formatters, content_type.to_sym => new_formatter)
end

#parser(content_type, new_parser) ⇒ Object

Specify a custom parser for a content-type.



38
39
40
 
# File 'lib/grape/dsl/request_response.rb', line 38

def parser(content_type, new_parser)
  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:



151
152
153
154
155
 
# File 'lib/grape/dsl/request_response.rb', line 151

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

  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) 


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
128
129
 
# File 'lib/grape/dsl/request_response.rb', line 97

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

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

  handler ||= extract_with(options)

  if args.include?(:all)
    namespace_inheritable(:rescue_all, true)
    namespace_inheritable(:all_rescue_handler, handler)
  elsif args.include?(:grape_exceptions)
    namespace_inheritable(:rescue_all, true)
    namespace_inheritable(:rescue_grape_exceptions, true)
    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

    namespace_reverse_stackable(handler_type, args.to_h { |arg| [arg, handler] })
  end

  namespace_stackable(:rescue_options, options)
end