Class: Grape::Endpoint

Inherits:
Object
  • Object
show all
Defined in:
lib/grape/endpoint.rb

Overview

An Endpoint is the proxy scope in which all routing blocks are executed. In other words, any methods on the instance level of this class may be called from inside a ‘get`, `post`, etc. block.

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(settings, options = {}, &block) ⇒ Endpoint

Returns a new instance of Endpoint.

Raises:

  • (ArgumentError) 


14
15
16
17
18
19
20
21
22
23
24
25
26
27
 
# File 'lib/grape/endpoint.rb', line 14

def initialize(settings, options = {}, &block)
  @settings = settings
  @block = block
  @options = options

  raise ArgumentError, "Must specify :path option." unless options.key?(:path)
  options[:path] = Array(options[:path])
  options[:path] = ['/'] if options[:path].empty?

  raise ArgumentError, "Must specify :method option." unless options.key?(:method)
  options[:method] = Array(options[:method])

  options[:route_options] ||= {}
end

Instance Attribute Details

#block ⇒ Object

Returns the value of attribute block.



11
12
13
 
# File 'lib/grape/endpoint.rb', line 11

def block
  @block
end

#env ⇒ Object (readonly)

Returns the value of attribute env.



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

def env
  @env
end

#options ⇒ Object

Returns the value of attribute options.



11
12
13
 
# File 'lib/grape/endpoint.rb', line 11

def options
  @options
end

#request ⇒ Object (readonly)

Returns the value of attribute request.



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

def request
  @request
end

#settings ⇒ Object

Returns the value of attribute settings.



11
12
13
 
# File 'lib/grape/endpoint.rb', line 11

def settings
  @settings
end

Instance Method Details

#body(value = nil) ⇒ Object

Allows you to define the response body as something other than the return value.

Examples:

get '/body' do
  body "Body"
  "Not the Body"
end

GET /body # => "Body"


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

def body(value = nil)
  if value
    @body = value
  else
    @body
  end
end

#body_params ⇒ Object

Pull out request body params if the content type matches and we’re on a POST or PUT



127
128
129
130
131
132
133
134
135
136
137
138
139
140
 
# File 'lib/grape/endpoint.rb', line 127

def body_params
  if ['POST', 'PUT'].include?(request.request_method.to_s.upcase)
    return case env['CONTENT_TYPE']
      when 'application/json'
        MultiJson.decode(request.body.read)
      when 'application/xml'
        MultiXml.parse(request.body.read)
      else
        {}
      end
  end

  {}
end

#call(env) ⇒ Object 



102
103
104
 
# File 'lib/grape/endpoint.rb', line 102

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

#call!(env) ⇒ Object 



106
107
108
109
110
111
112
113
114
115
 
# File 'lib/grape/endpoint.rb', line 106

def call!(env)
  env['api.endpoint'] = self
  if options[:app]
    options[:app].call(env)
  else
    builder = build_middleware
    builder.run options[:app] || lambda{|env| self.run(env) }
    builder.call(env)
  end
end

#compile_path(prepared_path, anchor = true, requirements = {}) ⇒ Object 



95
96
97
98
99
100
 
# File 'lib/grape/endpoint.rb', line 95

def compile_path(prepared_path, anchor = true, requirements = {})
  endpoint_options = {}
  endpoint_options[:version] = /#{settings[:version].join('|')}/ if settings[:version]
  endpoint_options.merge!(requirements)
  Rack::Mount::Strexp.compile(prepared_path, endpoint_options, %w( / . ? ), anchor)
end

#content_type(val) ⇒ Object

Set response content-type



202
203
204
 
# File 'lib/grape/endpoint.rb', line 202

def content_type(val)
  header('Content-Type', val)
end

#cookies ⇒ Object

Set or get a cookie

Examples:

cookies[:mycookie] = 'mycookie val'
cookies['mycookie-string'] = 'mycookie string val'
cookies[:more] = { :value => '123', :expires => Time.at(0) }
cookies.delete :more


214
215
216
 
# File 'lib/grape/endpoint.rb', line 214

def cookies
  @cookies ||= Cookies.new
end

#error!(message, status = 403) ⇒ Object

End the request and display an error to the end user with the specified message.

Parameters:

  • message (String) —

    The message to display.

  • status (Integer) (defaults to: 403) —

    the HTTP Status Code. Defaults to 403.



150
151
152
 
# File 'lib/grape/endpoint.rb', line 150

def error!(message, status=403)
  throw :error, :message => message, :status => status
end

#header(key = nil, val = nil) ⇒ Object

Set an individual header or retrieve all headers that have been set.



193
194
195
196
197
198
199
 
# File 'lib/grape/endpoint.rb', line 193

def header(key = nil, val = nil)
  if key
    val ? @header[key.to_s] = val : @header.delete(key.to_s)
  else
    @header
  end
end

#mount_in(route_set) ⇒ Object 



33
34
35
36
37
38
39
40
41
42
43
44
 
# File 'lib/grape/endpoint.rb', line 33

def mount_in(route_set)
  if options[:app] && options[:app].respond_to?(:endpoints)
    options[:app].endpoints.each{|e| e.mount_in(route_set)}
  else
    routes.each do |route|
      route_set.add_route(self, {
        :path_info => route.route_compiled,
        :request_method => route.route_method,
      }, { :route_info => route })
    end
  end
end

#namespace ⇒ Object 



91
92
93
 
# File 'lib/grape/endpoint.rb', line 91

def namespace
  Rack::Mount::Utils.normalize_path(settings.stack.map{|s| s[:namespace]}.join('/'))
end

#params ⇒ Object

The parameters passed into the request as well as parsed from URL segments.



119
120
121
122
123
124
 
# File 'lib/grape/endpoint.rb', line 119

def params
  @params ||= Hashie::Mash.new.
    deep_merge(request.params).
    deep_merge(env['rack.routing_args'] || {}).
    deep_merge(self.body_params)
end

#prepare_path(path) ⇒ Object 



82
83
84
85
86
87
88
89
 
# File 'lib/grape/endpoint.rb', line 82

def prepare_path(path)
  parts = []
  parts << settings[:root_prefix] if settings[:root_prefix]
  parts << ':version' if settings[:version] && settings[:version_options][:using] == :path
  parts << namespace.to_s if namespace
  parts << path.to_s if path && '/' != path
  Rack::Mount::Utils.normalize_path(parts.join('/') + '(.:format)')
end

#prepare_routes ⇒ Object 



46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
 
# File 'lib/grape/endpoint.rb', line 46

def prepare_routes
  routes = []
  options[:method].each do |method|
    options[:path].each do |path|
      prepared_path = prepare_path(path)

      anchor = options[:route_options][:anchor]
      anchor = anchor.nil? ? true : anchor

      requirements = options[:route_options][:requirements] || {}

      path = compile_path(prepared_path, anchor && !options[:app], requirements)
      regex = Rack::Mount::RegexpWithNamedGroups.new(path)
      path_params = {}
      # named parameters in the api path
      named_params = regex.named_captures.map { |nc| nc[0] } - [ 'version', 'format' ]
      named_params.each { |named_param| path_params[named_param] = "" }
      # route parameters declared via desc or appended to the api declaration
      route_params = (options[:route_options][:params] || {})
      path_params.merge!(route_params)
      request_method = (method.to_s.upcase unless method == :any)
      routes << Route.new(options[:route_options].clone.merge({
        :prefix => settings[:root_prefix],
        :version => settings[:version] ? settings[:version].join('|') : nil,
        :namespace => namespace,
        :method => request_method,
        :path => prepared_path,
        :params => path_params,
        :compiled => path,
        })
      )
    end
  end
  routes
end

#present(object, options = {}) ⇒ Object

Allows you to make use of Grape Entities by setting the response body to the serializable hash of the entity provided in the ‘:with` option. This has the added benefit of automatically passing along environment and version information to the serialization, making it very easy to do conditional exposures. See Entity docs for more info.

Examples:


get '/users/:id' do
  present User.find(params[:id]),
    :with => API::Entities::User,
    :admin => current_user.admin?
end


251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
 
# File 'lib/grape/endpoint.rb', line 251

def present(object, options = {})
  entity_class = options.delete(:with)

  object.class.ancestors.each do |potential|
    entity_class ||= (settings[:representations] || {})[potential]
  end

  root = options.delete(:root)

  representation = if entity_class
    embeds = {:env => env}
    embeds[:version] = env['api.version'] if env['api.version']
    entity_class.represent(object, embeds.merge(options))
  else
    object
  end

  representation = { root => representation } if root
  body representation
end

#redirect(url, options = {}) ⇒ Object

Redirect to a new url.

Parameters:

  • url (String) —

    The url to be redirect.

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

    The options used when redirect. :permanent, default true.



159
160
161
162
163
164
165
166
167
168
169
170
171
172
 
# File 'lib/grape/endpoint.rb', line 159

def redirect(url, options = {})
  merged_options = {:permanent => false }.merge(options)
  if merged_options[:permanent]
    status 304
  else
    if env['HTTP_VERSION'] == 'HTTP/1.1' && request.request_method.to_s.upcase != "GET"
      status 303
    else
      status 302
    end
  end
  header "Location", url
  body ""
end

#route ⇒ Object

Returns route information for the current request.

Examples:


desc "Returns the route description."
get '/' do
  route.route_description
end


280
281
282
 
# File 'lib/grape/endpoint.rb', line 280

def route
  env["rack.routing_args"][:route_info]
end

#routes ⇒ Object 



29
30
31
 
# File 'lib/grape/endpoint.rb', line 29

def routes
  @routes ||= prepare_routes
end

#status(status = nil) ⇒ Object

Set or retrieve the HTTP status code.

Parameters:

  • status (Integer) (defaults to: nil) —

    The HTTP Status Code to return for this request.



177
178
179
180
181
182
183
184
185
186
187
188
189
 
# File 'lib/grape/endpoint.rb', line 177

def status(status = nil)
  if status
    @status = status
  else
    return @status if @status
    case request.request_method.to_s.upcase
      when 'POST'
        201
      else
        200
    end
  end
end

#version ⇒ Object

The API version as specified in the URL.



143
 
# File 'lib/grape/endpoint.rb', line 143

def version; env['api.version'] end