Class: Grape::API
- Inherits:
-
Object
- Object
- Grape::API
- Extended by:
- Validations::ClassMethods
- Defined in:
- lib/grape/api.rb,
lib/grape/validations/coerce.rb
Overview
The API class is the primary entry point for creating Grape APIs.Users should subclass this class in order to build an API.
Constant Summary collapse
- Boolean =
Virtus::Attribute::Boolean
Class Attribute Summary collapse
-
.endpoints ⇒ Object
readonly
Returns the value of attribute endpoints.
-
.instance ⇒ Object
readonly
Returns the value of attribute instance.
- .logger(logger = nil) ⇒ Object
-
.route_set ⇒ Object
readonly
Returns the value of attribute route_set.
-
.routes ⇒ Object
readonly
An array of API routes.
-
.settings ⇒ Object
readonly
Returns the value of attribute settings.
-
.versions ⇒ Object
readonly
Returns the value of attribute versions.
Class Method Summary collapse
- .after(&block) ⇒ Object
- .after_validation(&block) ⇒ Object
-
.auth(type = nil, options = {}, &block) ⇒ Object
Add an authentication type to the API.
- .before(&block) ⇒ Object
- .call(env) ⇒ Object
- .call!(env) ⇒ Object
- .cascade(value = nil) ⇒ Object
- .change! ⇒ Object
- .compile ⇒ Object
-
.content_type(key, val) ⇒ Object
Specify additional content-types, e.g.: content_type :xls, 'application/vnd.ms-excel'.
-
.content_types ⇒ Object
All available content types.
-
.default_error_formatter(new_formatter = nil) ⇒ Object
Specify a default error formatter.
-
.default_error_status(new_status = nil) ⇒ Object
Specify the default status code for errors.
-
.default_format(new_format = nil) ⇒ Object
Specify the default format for the API's serializers.
- .delete(paths = ['/'], options = {}, &block) ⇒ Object
-
.desc(description, options = {}) ⇒ Object
Add a description to the next namespace or function.
-
.do_not_route_head! ⇒ Object
Do not route HEAD requests to GET requests automatically.
-
.do_not_route_options! ⇒ Object
Do not automatically route OPTIONS.
- .error_formatter(format, options) ⇒ Object
-
.format(new_format = nil) ⇒ Object
Specify the format for the API's serializers.
-
.formatter(content_type, new_formatter) ⇒ Object
Specify a custom formatter for a content-type.
- .get(paths = ['/'], options = {}, &block) ⇒ Object
- .head(paths = ['/'], options = {}, &block) ⇒ Object
-
.helpers(new_mod = nil, &block) ⇒ Object
Add helper methods that will be accessible from any endpoint within this namespace (and child namespaces).
-
.http_basic(options = {}, &block) ⇒ Object
Add HTTP Basic authorization to the API.
- .http_digest(options = {}, &block) ⇒ Object
-
.imbue(key, value) ⇒ Object
Add to a configuration value for this namespace.
-
.middleware ⇒ Object
Retrieve an array of the middleware classes and arguments that are currently applied to the application.
- .mount(mounts) ⇒ Object
- .namespace(space = nil, options = {}, &block) ⇒ Object (also: group, resource, resources, segment)
- .options(paths = ['/'], options = {}, &block) ⇒ Object
-
.parser(content_type, new_parser) ⇒ Object
Specify a custom parser for a content-type.
- .patch(paths = ['/'], options = {}, &block) ⇒ Object
- .post(paths = ['/'], options = {}, &block) ⇒ Object
-
.prefix(prefix = nil) ⇒ Object
Define a root URL prefix for your entire API.
- .put(paths = ['/'], options = {}, &block) ⇒ Object
-
.represent(model_class, options) ⇒ Object
Allows you to specify a default representation entity for a class.
-
.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.
- .reset! ⇒ Object
-
.route(methods, paths = ['/'], route_options = {}, &block) ⇒ Object
Defines a route that will be recognized by the Grape API.
-
.route_param(param, options = {}, &block) ⇒ Object
Thie method allows you to quickly define a parameter route segment in your API.
-
.scope(name = nil, &block) ⇒ Object
Create a scope without affecting the URL.
-
.set(key, value) ⇒ Object
Set a configuration value for this namespace.
-
.use(middleware_class, *args, &block) ⇒ Object
Apply a custom middleware to the API.
-
.version(*args, &block) ⇒ Object
Specify an API version.
Instance Method Summary collapse
- #call(env) ⇒ Object
-
#cascade? ⇒ Boolean
Some requests may return a HTTP 404 error if grape cannot find a matching route.
-
#initialize ⇒ API
constructor
A new instance of API.
Methods included from Validations::ClassMethods
document_attribute, params, reset_validations!
Constructor Details
#initialize ⇒ API
Returns a new instance of API.
483 484 485 486 487 488 489 490 |
# File 'lib/grape/api.rb', line 483 def initialize @route_set = Rack::Mount::RouteSet.new self.class.endpoints.each do |endpoint| endpoint.mount_in(@route_set) end add_head_not_allowed_methods @route_set.freeze end |
Class Attribute Details
.endpoints ⇒ Object (readonly)
Returns the value of attribute endpoints.
9 10 11 |
# File 'lib/grape/api.rb', line 9 def endpoints @endpoints end |
.instance ⇒ Object (readonly)
Returns the value of attribute instance.
9 10 11 |
# File 'lib/grape/api.rb', line 9 def instance @instance end |
.logger(logger = nil) ⇒ Object
12 13 14 15 16 17 18 |
# File 'lib/grape/api.rb', line 12 def logger(logger = nil) if logger @logger = logger else @logger ||= Logger.new($stdout) end end |
.route_set ⇒ Object (readonly)
Returns the value of attribute route_set.
9 10 11 |
# File 'lib/grape/api.rb', line 9 def route_set @route_set end |
.routes ⇒ Object (readonly)
An array of API routes.
429 430 431 |
# File 'lib/grape/api.rb', line 429 def routes @routes end |
.settings ⇒ Object (readonly)
Returns the value of attribute settings.
9 10 11 |
# File 'lib/grape/api.rb', line 9 def settings @settings end |
.versions ⇒ Object (readonly)
Returns the value of attribute versions.
9 10 11 |
# File 'lib/grape/api.rb', line 9 def versions @versions end |
Class Method Details
.after(&block) ⇒ Object
360 361 362 |
# File 'lib/grape/api.rb', line 360 def after(&block) imbue(:afters, [block]) end |
.after_validation(&block) ⇒ Object
356 357 358 |
# File 'lib/grape/api.rb', line 356 def after_validation(&block) imbue(:after_validations, [block]) end |
.auth(type = nil, options = {}, &block) ⇒ Object
Add an authentication type to the API. Currently
only :http_basic
, :http_digest
and :oauth2
are supported.
288 289 290 291 292 293 294 |
# File 'lib/grape/api.rb', line 288 def auth(type = nil, = {}, &block) if type set(:auth, {:type => type.to_sym, :proc => block}.merge()) else settings[:auth] end end |
.before(&block) ⇒ Object
352 353 354 |
# File 'lib/grape/api.rb', line 352 def before(&block) imbue(:befores, [block]) end |
.call(env) ⇒ Object
36 37 38 39 |
# File 'lib/grape/api.rb', line 36 def call(env) compile unless instance call!(env) end |
.call!(env) ⇒ Object
41 42 43 |
# File 'lib/grape/api.rb', line 41 def call!(env) instance.call(env) end |
.cascade(value = nil) ⇒ Object
437 438 439 440 441 |
# File 'lib/grape/api.rb', line 437 def cascade(value = nil) value.nil? ? (settings.has_key?(:cascade) ? !! settings[:cascade] : true) : set(:cascade, value) end |
.change! ⇒ Object
32 33 34 |
# File 'lib/grape/api.rb', line 32 def change! @instance = nil end |
.compile ⇒ Object
28 29 30 |
# File 'lib/grape/api.rb', line 28 def compile @instance = self.new end |
.content_type(key, val) ⇒ Object
Specify additional content-types, e.g.: content_type :xls, 'application/vnd.ms-excel'
166 167 168 |
# File 'lib/grape/api.rb', line 166 def content_type(key, val) settings.imbue(:content_types, key.to_sym => val) end |
.content_types ⇒ Object
All available content types.
171 172 173 |
# File 'lib/grape/api.rb', line 171 def content_types Grape::ContentTypes.content_types_for(settings[:content_types]) end |
.default_error_formatter(new_formatter = nil) ⇒ Object
Specify a default error formatter.
150 151 152 |
# File 'lib/grape/api.rb', line 150 def default_error_formatter(new_formatter = nil) new_formatter ? set(:default_error_formatter, new_formatter) : settings[:default_error_formatter] end |
.default_error_status(new_status = nil) ⇒ Object
Specify the default status code for errors.
176 177 178 |
# File 'lib/grape/api.rb', line 176 def default_error_status(new_status = nil) new_status ? set(:default_error_status, new_status) : settings[:default_error_status] end |
.default_format(new_format = nil) ⇒ Object
Specify the default format for the API's serializers.
May be :json
or :txt
(default).
119 120 121 |
# File 'lib/grape/api.rb', line 119 def default_format(new_format = nil) new_format ? set(:default_format, new_format.to_sym) : settings[:default_format] end |
.delete(paths = ['/'], options = {}, &block) ⇒ Object
368 |
# File 'lib/grape/api.rb', line 368 def delete(paths = ['/'], = {}, &block); route('DELETE', paths, , &block) end |
.desc(description, options = {}) ⇒ Object
Add a description to the next namespace or function.
113 114 115 |
# File 'lib/grape/api.rb', line 113 def desc(description, = {}) @last_description = .merge(:description => description) end |
.do_not_route_head! ⇒ Object
Do not route HEAD requests to GET requests automatically
68 69 70 |
# File 'lib/grape/api.rb', line 68 def do_not_route_head! set(:do_not_route_head, true) end |
.do_not_route_options! ⇒ Object
Do not automatically route OPTIONS
73 74 75 |
# File 'lib/grape/api.rb', line 73 def set(:do_not_route_options, true) end |
.error_formatter(format, options) ⇒ Object
154 155 156 157 158 159 160 161 162 |
# File 'lib/grape/api.rb', line 154 def error_formatter(format, ) if .is_a?(Hash) && .has_key?(:with) formatter = [:with] else formatter = end settings.imbue(: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.
125 126 127 128 129 130 131 132 133 134 135 136 137 |
# File 'lib/grape/api.rb', line 125 def format(new_format = nil) if new_format set(:format, new_format.to_sym) # define the default error formatters set(:default_error_formatter, Grape::ErrorFormatter::Base.formatter_for(new_format, {})) # define a single mime type mime_type = content_types[new_format.to_sym] raise Grape::Exceptions::MissingMimeType.new(new_format) unless mime_type settings.imbue(:content_types, new_format.to_sym => mime_type) else settings[:format] end end |
.formatter(content_type, new_formatter) ⇒ Object
Specify a custom formatter for a content-type.
140 141 142 |
# File 'lib/grape/api.rb', line 140 def formatter(content_type, new_formatter) settings.imbue(:formatters, content_type.to_sym => new_formatter) end |
.get(paths = ['/'], options = {}, &block) ⇒ Object
364 |
# File 'lib/grape/api.rb', line 364 def get(paths = ['/'], = {}, &block); route('GET', paths, , &block) end |
.head(paths = ['/'], options = {}, &block) ⇒ Object
367 |
# File 'lib/grape/api.rb', line 367 def head(paths = ['/'], = {}, &block); route('HEAD', paths, , &block) end |
.helpers(new_mod = nil, &block) ⇒ Object
Add helper methods that will be accessible from any endpoint within this namespace (and child namespaces).
When called without a block, all known helpers within this scope are included.
266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 |
# File 'lib/grape/api.rb', line 266 def helpers(new_mod = nil, &block) if block_given? || new_mod mod = settings.peek[:helpers] || Module.new if new_mod mod.class_eval do include new_mod end end mod.class_eval &block if block_given? set(:helpers, mod) else mod = Module.new settings.stack.each do |s| mod.send :include, s[:helpers] if s[:helpers] end change! mod end end |
.http_basic(options = {}, &block) ⇒ Object
Add HTTP Basic authorization to the API.
300 301 302 303 |
# File 'lib/grape/api.rb', line 300 def http_basic( = {}, &block) [:realm] ||= "API Authorization" auth :http_basic, , &block end |
.http_digest(options = {}, &block) ⇒ Object
305 306 307 308 309 |
# File 'lib/grape/api.rb', line 305 def http_digest( = {}, &block) [:realm] ||= "API Authorization" [:opaque] ||= "secret" auth :http_digest, , &block end |
.imbue(key, value) ⇒ Object
Add to a configuration value for this namespace.
58 59 60 |
# File 'lib/grape/api.rb', line 58 def imbue(key, value) settings.imbue(key, value) end |
.middleware ⇒ Object
Retrieve an array of the middleware classes and arguments that are currently applied to the application.
424 425 426 |
# File 'lib/grape/api.rb', line 424 def middleware settings.stack.inject([]){|a,s| a += s[:middleware] if s[:middleware]; a} end |
.mount(mounts) ⇒ Object
311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 |
# File 'lib/grape/api.rb', line 311 def mount(mounts) mounts = { mounts => '/' } unless mounts.respond_to?(:each_pair) mounts.each_pair do |app, path| if app.respond_to?(:inherit_settings, true) app_settings = settings.clone mount_path = Rack::Mount::Utils.normalize_path([ settings[:mount_path], path ].compact.join("/")) app_settings.set :mount_path, mount_path app.inherit_settings(app_settings) end endpoints << Grape::Endpoint.new(settings.clone, { :method => :any, :path => path, :app => app }) end end |
.namespace(space = nil, options = {}, &block) ⇒ Object Also known as: group, resource, resources, segment
372 373 374 375 376 377 378 379 380 381 382 383 384 |
# File 'lib/grape/api.rb', line 372 def namespace(space = nil, = {}, &block) if space || block_given? previous_namespace_description = @namespace_description @namespace_description = (@namespace_description || {}).deep_merge(@last_description || {}) @last_description = nil nest(block) do set(:namespace, Namespace.new(space, )) if space end @namespace_description = previous_namespace_description else Namespace.joined_space_path(settings) end end |
.options(paths = ['/'], options = {}, &block) ⇒ Object
369 |
# File 'lib/grape/api.rb', line 369 def (paths = ['/'], = {}, &block); route('OPTIONS', paths, , &block) end |
.parser(content_type, new_parser) ⇒ Object
Specify a custom parser for a content-type.
145 146 147 |
# File 'lib/grape/api.rb', line 145 def parser(content_type, new_parser) settings.imbue(:parsers, content_type.to_sym => new_parser) end |
.patch(paths = ['/'], options = {}, &block) ⇒ Object
370 |
# File 'lib/grape/api.rb', line 370 def patch(paths = ['/'], = {}, &block); route('PATCH', paths, , &block) end |
.post(paths = ['/'], options = {}, &block) ⇒ Object
365 |
# File 'lib/grape/api.rb', line 365 def post(paths = ['/'], = {}, &block); route('POST', paths, , &block) end |
.prefix(prefix = nil) ⇒ Object
Define a root URL prefix for your entire API.
63 64 65 |
# File 'lib/grape/api.rb', line 63 def prefix(prefix = nil) prefix ? set(:root_prefix, prefix) : settings[:root_prefix] end |
.put(paths = ['/'], options = {}, &block) ⇒ Object
366 |
# File 'lib/grape/api.rb', line 366 def put(paths = ['/'], = {}, &block); route('PUT', paths, , &block) 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.
242 243 244 245 |
# File 'lib/grape/api.rb', line 242 def represent(model_class, ) raise Grape::Exceptions::InvalidWithOptionForRepresent.new unless [:with] && [:with].is_a?(Class) imbue(:representations, model_class => [: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.
199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 |
# File 'lib/grape/api.rb', line 199 def rescue_from(*args, &block) if args.last.is_a?(Proc) handler = args.pop elsif block_given? handler = block end = args.last.is_a?(Hash) ? args.pop : {} if .has_key?(:with) handler ||= proc { [:with] } end if handler args.each do |arg| imbue(:rescue_handlers, { arg => handler }) end end imbue(:rescue_options, ) set(:rescue_all, true) and return if args.include?(:all) imbue(:rescued_errors, args) end |
.reset! ⇒ Object
20 21 22 23 24 25 26 |
# File 'lib/grape/api.rb', line 20 def reset! @settings = Grape::Util::HashStack.new @route_set = Rack::Mount::RouteSet.new @endpoints = [] @routes = nil reset_validations! end |
.route(methods, paths = ['/'], route_options = {}, &block) ⇒ Object
Defines a route that will be recognized by the Grape API.
340 341 342 343 344 345 346 347 348 349 350 |
# File 'lib/grape/api.rb', line 340 def route(methods, paths = ['/'], = {}, &block) = { :method => methods, :path => paths, :route_options => (@namespace_description || {}).deep_merge(@last_description || {}).deep_merge( || {}) } endpoints << Grape::Endpoint.new(settings.clone, , &block) @last_description = nil reset_validations! end |
.route_param(param, options = {}, &block) ⇒ Object
Thie method allows you to quickly define a parameter route segment in your API.
391 392 393 394 395 |
# File 'lib/grape/api.rb', line 391 def route_param(param, = {}, &block) = .dup [:requirements] = { param.to_sym => [:requirements] } if [:requirements].is_a?(Regexp) namespace(":#{param}", , &block) end |
.scope(name = nil, &block) ⇒ Object
Create a scope without affecting the URL.
405 406 407 |
# File 'lib/grape/api.rb', line 405 def scope(name = nil, &block) nest(block) end |
.set(key, value) ⇒ Object
Set a configuration value for this namespace.
49 50 51 |
# File 'lib/grape/api.rb', line 49 def set(key, value) settings[key.to_sym] = value end |
.use(middleware_class, *args, &block) ⇒ Object
Apply a custom middleware to the API. Applies to the current namespace and any children, but not parents.
415 416 417 418 419 |
# File 'lib/grape/api.rb', line 415 def use(middleware_class, *args, &block) arr = [middleware_class, *args] arr << block if block_given? imbue(:middleware, [arr]) end |
.version(*args, &block) ⇒ Object
Specify an API version.
94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 |
# File 'lib/grape/api.rb', line 94 def version(*args, &block) if args.any? = args.pop if args.last.is_a? Hash ||= {} = {:using => :path}.merge!() raise Grape::Exceptions::MissingVendorOption.new if [:using] == :header && !.has_key?(:vendor) @versions = versions | args nest(block) do set(:version, args) set(:version_options, ) end end @versions.last unless @versions.nil? end |
Instance Method Details
#call(env) ⇒ Object
492 493 494 495 496 |
# File 'lib/grape/api.rb', line 492 def call(env) status, headers, body = @route_set.call(env) headers.delete('X-Cascade') unless cascade? [ status, headers, body ] end |
#cascade? ⇒ Boolean
Some requests may return a HTTP 404 error if grape cannot find a matching route. In this case, Rack::Mount 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.
506 507 508 509 510 |
# File 'lib/grape/api.rb', line 506 def cascade? return !! self.class.settings[:cascade] if self.class.settings.has_key?(:cascade) return !! self.class.settings[:version_options][:cascade] if self.class.settings[:version_options] && self.class.settings[:version_options].has_key?(:cascade) true end |