Class: Grape::API::Instance

Inherits:
Object
  • Object
show all
Extended by:
Forwardable, DSL::Callbacks, DSL::Desc, DSL::Helpers, DSL::Logger, DSL::Middleware, DSL::RequestResponse, DSL::Routing, DSL::Settings, DSL::Validations, Middleware::Auth::DSL
Defined in:
lib/grape/api/instance.rb

Overview

The API Instance class, is the engine behind Grape::API. Each class that inherits from this will represent a different API instance

Constant Summary collapse

Boolean = 
Grape::API::Boolean
LOCK =

A class-level lock to ensure the API is not compiled by multiple threads simultaneously within the same process.

Mutex.new

Class Attribute Summary collapse

Instance Attribute Summary collapse

Attributes included from DSL::Settings

#inheritable_setting, #top_level_setting

Attributes included from DSL::Routing

#endpoints

Class Method Summary collapse

Instance Method Summary collapse

Methods included from DSL::Settings

global_setting, namespace_setting, route_setting

Methods included from DSL::Desc

desc

Methods included from DSL::Validations

contract, params, reset_validations!

Methods included from DSL::Logger

logger

Methods included from DSL::Middleware

middleware, use

Methods included from DSL::RequestResponse

content_type, content_types, default_error_formatter, default_error_status, default_format, error_formatter, format, formatter, parser, represent, rescue_from

Methods included from DSL::Routing

build_with, do_not_document!, do_not_route_head!, do_not_route_options!, lint!, mount, namespace, prefix, reset_endpoints!, reset_routes!, route, route_param, routes, scope, version, versions

Methods included from DSL::Helpers

helpers

Methods included from Middleware::Auth::DSL

auth, http_basic, http_digest

Constructor Details

#initialize ⇒ Instance

Builds the routes from the defined endpoints, effectively compiling this API into a usable form.



131
132
133
134
135
136
137
138
139
140
 
# File 'lib/grape/api/instance.rb', line 131

def initialize
  @router = Router.new
  add_head_not_allowed_methods_and_options_methods
  self.class.endpoints.each do |endpoint|
    endpoint.mount_in(@router)
  end

  @router.compile!
  @router.freeze
end

Class Attribute Details

.base ⇒ Object

Returns the value of attribute base.



24
25
26
 
# File 'lib/grape/api/instance.rb', line 24

def base
  @base
end

.configuration ⇒ Object

Returns the value of attribute configuration.



25
26
27
 
# File 'lib/grape/api/instance.rb', line 25

def configuration
  @configuration
end

.instance ⇒ Object (readonly)

Returns the value of attribute instance.



24
25
26
 
# File 'lib/grape/api/instance.rb', line 24

def instance
  @instance
end

Instance Attribute Details

#router ⇒ Object (readonly)

Returns the value of attribute router.



127
128
129
 
# File 'lib/grape/api/instance.rb', line 127

def router
  @router
end

Class Method Details

.base_instance? ⇒ Boolean

Returns:



44
45
46
 
# File 'lib/grape/api/instance.rb', line 44

def base_instance?
  self == base.base_instance
end

.call(env) ⇒ Object

This is the interface point between Rack and Grape; it accepts a request from Rack and ultimately returns an array of three values: the status, the headers, and the body. See [the rack specification] (www.rubydoc.info/github/rack/rack/master/file/SPEC) for more.



69
70
71
72
 
# File 'lib/grape/api/instance.rb', line 69

def call(env)
  compile!
  call!(env)
end

.call!(env) ⇒ Object

A non-synchronized version of ::call.



75
76
77
 
# File 'lib/grape/api/instance.rb', line 75

def call!(env)
  instance.call(env)
end

.cascade(value = nil) ⇒ Object

Some requests may return a HTTP 404 error if grape cannot find a matching route. In this case, Grape::Router adds a X-Cascade header to the response and sets it to ‘pass’, indicating to grape’s parents they should keep looking for a matching route on other resources.

In some applications (e.g. mounting grape on rails), one might need to trap errors from reaching upstream. This is effectivelly done by unsetting X-Cascade. Default :cascade is true.



80
81
82
83
84
 
# File 'lib/grape/api/instance.rb', line 80

def cascade(value = nil)
  return inheritable_setting.namespace_inheritable.key?(:cascade) ? !inheritable_setting.namespace_inheritable(:cascade).nil? : true if value.nil?

  inheritable_setting.namespace_inheritable[:cascade] = value
end

.compile ⇒ Object

Parses the API’s definition and compiles it into an instance of Grape::API.



61
62
63
 
# File 'lib/grape/api/instance.rb', line 61

def compile
  @instance ||= new # rubocop:disable Naming/MemoizedInstanceVariableName
end

.compile! ⇒ Object 



86
87
88
89
90
 
# File 'lib/grape/api/instance.rb', line 86

def compile!
  return if instance

  LOCK.synchronize { compile unless instance }
end

.given(conditional_option, &block) ⇒ Object 



29
30
31
32
33
 
# File 'lib/grape/api/instance.rb', line 29

def given(conditional_option, &block)
  return unless conditional_option

  mounted(&block)
end

.mounted(&block) ⇒ Object 



35
36
37
 
# File 'lib/grape/api/instance.rb', line 35

def mounted(&block)
  evaluate_as_instance_with_configuration(block, lazy: true)
end

.recognize_path(path) ⇒ Object

see Grape::Router#recognize_path



93
94
95
96
 
# File 'lib/grape/api/instance.rb', line 93

def recognize_path(path)
  compile!
  instance.router.recognize_path(path)
end

.reset! ⇒ Object

Clears all defined routes, endpoints, etc., on this API.



53
54
55
56
57
 
# File 'lib/grape/api/instance.rb', line 53

def reset!
  reset_endpoints!
  reset_routes!
  reset_validations!
end

Instance Method Details

#call(env) ⇒ Object

Handle a request. See Rack documentation for what ‘env` is.



143
144
145
146
147
148
149
150
151
 
# File 'lib/grape/api/instance.rb', line 143

def call(env)
  status, headers, response = @router.call(env)
  unless cascade?
    headers = Grape::Util::Header.new.merge(headers)
    headers.delete('X-Cascade')
  end

  [status, headers, response]
end

#cascade? ⇒ Boolean

Some requests may return a HTTP 404 error if grape cannot find a matching route. In this case, Grape::Router adds a X-Cascade header to the response and sets it to ‘pass’, indicating to grape’s parents they should keep looking for a matching route on other resources.

In some applications (e.g. mounting grape on rails), one might need to trap errors from reaching upstream. This is effectivelly done by unsetting X-Cascade. Default :cascade is true.

Returns:



161
162
163
164
165
166
167
 
# File 'lib/grape/api/instance.rb', line 161

def cascade?
  namespace_inheritable = self.class.inheritable_setting.namespace_inheritable
  return namespace_inheritable[:cascade] if namespace_inheritable.key?(:cascade)
  return namespace_inheritable[:version_options][:cascade] if namespace_inheritable[:version_options]&.key?(:cascade)

  true
end