Class: Grape::API

Inherits:
Object
  • Object
show all
Defined in:
lib/grape/api.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.

Class Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize ⇒ API

Returns a new instance of API.



390
391
392
393
394
395
396
 
# File 'lib/grape/api.rb', line 390

def initialize
  @route_set = Rack::Mount::RouteSet.new
  self.class.endpoints.each do |endpoint|
    endpoint.mount_in(@route_set)
  end
  @route_set.freeze
end

Class Attribute Details

.endpoints ⇒ Object (readonly)

Returns the value of attribute endpoints.



17
18
19
 
# File 'lib/grape/api.rb', line 17

def endpoints
  @endpoints
end

.instance ⇒ Object (readonly)

Returns the value of attribute instance.



19
20
21
 
# File 'lib/grape/api.rb', line 19

def instance
  @instance
end

.logger(logger = nil) ⇒ Object 



21
22
23
24
25
26
27
 
# File 'lib/grape/api.rb', line 21

def logger(logger = nil)
  if logger
    @logger = logger
  else
    @logger ||= Logger.new($stdout)
  end
end

.mountings ⇒ Object (readonly)

Returns the value of attribute mountings.



18
19
20
 
# File 'lib/grape/api.rb', line 18

def mountings
  @mountings
end

.route_set ⇒ Object (readonly)

Returns the value of attribute route_set.



12
13
14
 
# File 'lib/grape/api.rb', line 12

def route_set
  @route_set
end

.routes ⇒ Object (readonly)

An array of API routes.



346
347
348
 
# File 'lib/grape/api.rb', line 346

def routes
  @routes
end

.settings ⇒ Object (readonly)

Returns the value of attribute settings.



15
16
17
 
# File 'lib/grape/api.rb', line 15

def settings
  @settings
end

.versions ⇒ Object (readonly)

Returns the value of attribute versions.



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

def versions
  @versions
end

Class Method Details

.after(&block) ⇒ Object 



292
293
294
 
# File 'lib/grape/api.rb', line 292

def after(&block)
  imbue(:afters, [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.



228
229
230
231
232
233
234
 
# File 'lib/grape/api.rb', line 228

def auth(type = nil, options = {}, &block)
  if type
    set(:auth, {:type => type.to_sym, :proc => block}.merge(options))
  else
    settings[:auth]
  end
end

.before(&block) ⇒ Object 



288
289
290
 
# File 'lib/grape/api.rb', line 288

def before(&block)
  imbue(:befores, [block])
end

.call(env) ⇒ Object 



45
46
47
48
 
# File 'lib/grape/api.rb', line 45

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

.call!(env) ⇒ Object 



50
51
52
 
# File 'lib/grape/api.rb', line 50

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

.change! ⇒ Object 



41
42
43
 
# File 'lib/grape/api.rb', line 41

def change!
  @instance = nil
end

.compile ⇒ Object 



37
38
39
 
# File 'lib/grape/api.rb', line 37

def compile
  @instance = self.new
end

.content_type(key, val) ⇒ Object

Specify additional content-types, e.g.:

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



132
133
134
 
# File 'lib/grape/api.rb', line 132

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

.default_error_status(new_status = nil) ⇒ Object

Specify the default status code for errors.



137
138
139
 
# File 'lib/grape/api.rb', line 137

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).



114
115
116
 
# File 'lib/grape/api.rb', line 114

def default_format(new_format = nil)
  new_format ? set(:default_format, new_format.to_sym) : settings[:default_format]
end

.delete(paths = ['/'], options = {}, &block) ⇒ Object 



300
 
# File 'lib/grape/api.rb', line 300

def delete(paths = ['/'], options = {}, &block); route('DELETE', paths, options, &block) end

.desc(description, options = {}) ⇒ Object

Add a description to the next namespace or function.



108
109
110
 
# File 'lib/grape/api.rb', line 108

def desc(description, options = {})
  @last_description = options.merge(:description => description)
end

.error_format(new_format = nil) ⇒ Object

Specify the format for error messages. May be :json or :txt (default).



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

def error_format(new_format = nil)
  new_format ? set(:error_format, new_format.to_sym) : settings[:error_format]
end

.format(new_format = nil) ⇒ Object

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



120
121
122
 
# File 'lib/grape/api.rb', line 120

def format(new_format = nil)
  new_format ? set(:format, new_format.to_sym) : settings[:format]
end

.get(paths = ['/'], options = {}, &block) ⇒ Object 



296
 
# File 'lib/grape/api.rb', line 296

def get(paths = ['/'], options = {}, &block); route('GET', paths, options, &block) end

.head(paths = ['/'], options = {}, &block) ⇒ Object 



299
 
# File 'lib/grape/api.rb', line 299

def head(paths = ['/'], options = {}, &block); route('HEAD', paths, options, &block) end

.helpers(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.

Examples:

Define some helpers.

class ExampleAPI < Grape::API
  helpers do
    def current_user
      User.find_by_id(params[:token])
    end
  end
end

Parameters:

  • mod (Module) (defaults to: nil) —

    optional module of methods to include

  • &block (Block) —

    optional block of methods to include



211
212
213
214
215
216
217
218
219
220
221
222
223
224
 
# File 'lib/grape/api.rb', line 211

def helpers(mod = nil, &block)
  if block_given? || mod
    mod ||= settings.peek[:helpers] || Module.new
    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.

Parameters:

  • options (Hash) (defaults to: {}) —

    A hash of options.

Options Hash (options):

  • :realm (String) —

    “API Authorization” The HTTP Basic realm.



240
241
242
243
 
# File 'lib/grape/api.rb', line 240

def http_basic(options = {}, &block)
  options[:realm] ||= "API Authorization"
  auth :http_basic, options, &block
end

.http_digest(options = {}, &block) ⇒ Object 



245
246
247
248
249
 
# File 'lib/grape/api.rb', line 245

def http_digest(options = {}, &block)
  options[:realm] ||= "API Authorization"
  options[:opaque] ||= "secret"
  auth :http_digest, options, &block
end

.imbue(key, value) ⇒ Object

Add to a configuration value for this namespace.

Parameters:

  • key (Symbol) —

    The key of the configuration variable.

  • value (Object) —

    The value to which to set the configuration variable.



67
68
69
 
# File 'lib/grape/api.rb', line 67

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.



341
342
343
 
# File 'lib/grape/api.rb', line 341

def middleware
  settings.stack.inject([]){|a,s| a += s[:middleware] if s[:middleware]; a}
end

.mount(mounts) ⇒ Object 



251
252
253
254
255
256
257
258
259
260
261
262
263
264
 
# File 'lib/grape/api.rb', line 251

def mount(mounts)
  mounts = {mounts => '/'} unless mounts.respond_to?(:each_pair)
  mounts.each_pair do |app, path|
    if app.respond_to?(:inherit_settings)
      app.inherit_settings(settings.clone)
    end

    endpoints << Grape::Endpoint.new(settings.clone,
      :method => :any,
      :path => path,
      :app => app
    )
  end
end

.namespace(space = nil, &block) ⇒ Object Also known as: group, resource, resources, segment 



304
305
306
307
308
309
310
311
312
 
# File 'lib/grape/api.rb', line 304

def namespace(space = nil, &block)
  if space || block_given?
    nest(block) do
      set(:namespace, space.to_s) if space
    end
  else
    Rack::Mount::Utils.normalize_path(settings.stack.map{|s| s[:namespace]}.join('/'))
  end
end

.options(paths = ['/'], options = {}, &block) ⇒ Object 



301
 
# File 'lib/grape/api.rb', line 301

def options(paths = ['/'], options = {}, &block); route('OPTIONS', paths, options, &block) end

.patch(paths = ['/'], options = {}, &block) ⇒ Object 



302
 
# File 'lib/grape/api.rb', line 302

def patch(paths = ['/'], options = {}, &block); route('PATCH', paths, options, &block) end

.post(paths = ['/'], options = {}, &block) ⇒ Object 



297
 
# File 'lib/grape/api.rb', line 297

def post(paths = ['/'], options = {}, &block); route('POST', paths, options, &block) end

.prefix(prefix = nil) ⇒ Object

Define a root URL prefix for your entire API.



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

def prefix(prefix = nil)
  prefix ? set(:root_prefix, prefix) : settings[:root_prefix]
end

.put(paths = ['/'], options = {}, &block) ⇒ Object 



298
 
# File 'lib/grape/api.rb', line 298

def put(paths = ['/'], options = {}, &block); route('PUT', paths, options, &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.

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:

  • (ArgumentError) 


189
190
191
192
 
# File 'lib/grape/api.rb', line 189

def represent(model_class, options)
  raise ArgumentError, "You must specify an entity class in the :with option." unless options[:with] && options[:with].is_a?(Class)
  imbue(: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) (defaults to: {}) —

    Options for the rescue usage.

Options Hash (options):

  • :backtrace (Boolean) —

    Include a backtrace in the rescue response.



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

def rescue_from(*args, &block)
  if block_given?
    args.each do |arg|
      imbue(:rescue_handlers, { arg => block })
    end
  end
  imbue(:rescue_options, args.pop) if args.last.is_a?(Hash)
  set(:rescue_all, true) and return if args.include?(:all)
  imbue(:rescued_errors, args)
end

.reset! ⇒ Object 



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

def reset!
  @settings  = Grape::Util::HashStack.new
  @route_set = Rack::Mount::RouteSet.new
  @endpoints = []
  @mountings = []
  @routes = nil
end

.route(methods, paths = ['/'], route_options = {}, &block) ⇒ Object

Defines a route that will be recognized by the Grape API.

Examples:

Defining a basic route.

class MyAPI < Grape::API
  route(:any, '/hello') do
    {:hello => 'world'}
  end
end

Parameters:

  • methods (HTTP Verb) —

    One or more HTTP verbs that are accepted by this route. Set to :any if you want any verb to be accepted.

  • paths (String) (defaults to: ['/']) —

    One or more strings representing the URL segment(s) for this route.



278
279
280
281
282
283
284
285
286
 
# File 'lib/grape/api.rb', line 278

def route(methods, paths = ['/'], route_options = {}, &block)
  endpoint_options = {
    :method => methods,
    :path => paths,
    :route_options => (route_options || {}).merge(@last_description || {})
  }
  endpoints << Grape::Endpoint.new(settings.clone, endpoint_options, &block)
  @last_description = nil
end

.scope(name = nil, &block) ⇒ Object

Create a scope without affecting the URL.

Parameters:

  • name (Symbol) (defaults to: nil) —

    Purely placebo, just allows to to name the scope to make the code more readable.



322
323
324
 
# File 'lib/grape/api.rb', line 322

def scope(name = nil, &block)
  nest(block)
end

.set(key, value) ⇒ Object

Set a configuration value for this namespace.

Parameters:

  • key (Symbol) —

    The key of the configuration variable.

  • value (Object) —

    The value to which to set the configuration variable.



58
59
60
 
# File 'lib/grape/api.rb', line 58

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.

Parameters:

  • middleware_class (Class) —

    The class of the middleware you’d like to inject.



332
333
334
335
336
 
# File 'lib/grape/api.rb', line 332

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.

Examples:

API with legacy support.

class MyAPI < Grape::API
  version 'v2'

  get '/main' do
    {:some => 'data'}
  end

  version 'v1' do
    get '/main' do
      {:legacy => 'data'}
    end
  end
end


94
95
96
97
98
99
100
101
102
103
104
105
 
# File 'lib/grape/api.rb', line 94

def version(*args, &block)
  if args.any?
    options = args.pop if args.last.is_a? Hash
    options ||= {}
    options = {:using => :path}.merge!(options)
    @versions = versions | args
    nest(block) do
      set(:version, args)
      set(:version_options, options)
    end
  end
end

Instance Method Details

#call(env) ⇒ Object 



398
399
400
 
# File 'lib/grape/api.rb', line 398

def call(env)
  @route_set.call(env)
end