grape 0.2.3 → 0.2.4

data/.yardopts

@@ -0,0 +1,2 @@
+--markup-provider=redcarpet
+--markup=markdown

data/CHANGELOG.markdown

@@ -1,3 +1,22 @@
+0.2.4 (01/06/2013)
+==================
+
+* [#297](https://github.com/intridea/grape/issues/297): Added `default_error_formatter` - [@dblock](https://github.com/dblock).
+* [#297](https://github.com/intridea/grape/issues/297): Setting `format` will automatically set `default_error_formatter` - [@dblock](https://github.com/dblock).
+* [#295](https://github.com/intridea/grape/issues/295): Storing original API source block in endpoint's `source` attribute - [@dblock](https://github.com/dblock).
+* [#293](https://github.com/intridea/grape/pull/293): Added options to `cookies.delete`, enables passing a path - [@inst](https://github.com/inst).
+* [#174](https://github.com/intridea/grape/issues/174): The value of `env['PATH_INFO']` is no longer altered with `path` versioning - [@dblock](https://github.com/dblock).
+* [#296](https://github.com/intridea/grape/issues/296): Fix: ArgumentError with default error formatter - [@dblock](https://github.com/dblock).
+* [#298](https://github.com/intridea/grape/pull/298): Fix: subsequent calls to `body_params` would fail due to IO read - [@justinmcp](https://github.com/justinmcp).
+* [#301](https://github.com/intridea/grape/issues/301): Fix: symbol memory leak in cookie and formatter middleware - [@dblock](https://github.com/dblock).
+* [#300](https://github.com/intridea/grape/issues/300): Fix `Grape::API.routes` to include mounted api routes - [@aiwilliams](https://github.com/aiwilliams).
+* [#302](https://github.com/intridea/grape/pull/302): Fix: removed redundant `autoload` entries - [@ugisozols](https://github.com/ugisozols).
+* [#172](https://github.com/intridea/grape/issues/172): Fix: MultiJson deprecated methods warnings - [@dblock](https://github.com/dblock).
+* [#133](https://github.com/intridea/grape/issues/133): Fix: header-based versioning with use of `prefix` - [@seanmoon](https://github.com/seanmoon), [@dblock](https://github.com/dblock).
+* [#280](https://github.com/intridea/grape/issues/280): Fix: grouped parameters mangled in `route_params` hash - [@marcusg](https://github.com/marcusg), [@dblock](https://github.com/dblock).
+* [#304](https://github.com/intridea/grape/issues/304): Fix: `present x, :with => Entity` returns class references with `format :json` - [@dblock](https://github.com/dblock).
+* [#196](https://github.com/intridea/grape/issues/196): Fix: root requests don't work with `prefix` - [@dblock](https://github.com/dblock).
+
 0.2.3 (24/12/2012)
 ==================
 

data/Gemfile

@@ -12,4 +12,6 @@ group :development, :test do
   gem 'json'
   gem 'rspec'
   gem 'rack-test', "~> 0.6.2", :require => "rack/test"
+  gem 'github-markup'
+  gem 'redcarpet'
 end

data/README.markdown

@@ -15,11 +15,6 @@ content negotiation, versioning and much more.
 * [Grape Google Group](http://groups.google.com/group/ruby-grape)
 * [Grape Wiki](https://github.com/intridea/grape/wiki)
 
-## Stable Release
-
-You're reading the documentation for the next release of Grape, which should be 0.2.3.
-The current stable release is [0.2.2](https://github.com/intridea/grape/blob/v0.2.2/README.markdown).
-
 ## Installation
 
 Grape is available as a gem, to install it just install the gem:
@@ -38,78 +33,80 @@ Grape APIs are Rack applications that are created by subclassing `Grape::API`.
 Below is a simple example showing some of the more common features of Grape in
 the context of recreating parts of the Twitter API.
 
-``` ruby
-class Twitter::API < Grape::API
-  version 'v1', :using => :header, :vendor => 'twitter'
-  format :json
+```ruby
+module Twitter
+  class API < Grape::API
 
-  helpers do
-    def current_user
-      @current_user ||= User.authorize!(env)
-    end
+    version 'v1', :using => :header, :vendor => 'twitter'
+    format :json
+
+    helpers do
+      def current_user
+        @current_user ||= User.authorize!(env)
+      end
 
-    def authenticate!
-      error!('401 Unauthorized', 401) unless current_user
+      def authenticate!
+        error!('401 Unauthorized', 401) unless current_user
+      end
     end
-  end
 
-  resource :statuses do
+    resource :statuses do
 
-    desc "Return a public timeline."
-    get :public_timeline do
-      Status.limit(20)
-    end
+      desc "Return a public timeline."
+      get :public_timeline do
+        Status.limit(20)
+      end
 
-    desc "Return a personal timeline."
-    get :home_timeline do
-      authenticate!
-      current_user.statuses.limit(20)
-    end
+      desc "Return a personal timeline."
+      get :home_timeline do
+        authenticate!
+        current_user.statuses.limit(20)
+      end
 
-    desc "Return a status."
-    params do
-      requires :id, :type => Integer, :desc => "Status id."
-    end
-    get ':id' do
-      Status.find(params[:id])
-    end
+      desc "Return a status."
+      params do
+        requires :id, :type => Integer, :desc => "Status id."
+      end
+      get ':id' do
+        Status.find(params[:id])
+      end
 
-    desc "Create a status."
-    params do
-      requires :status, :type => String, :desc => "Your status."
-    end
-    post do
-      authenticate!
-      Status.create!({
-        :user => current_user,
-        :text => params[:status]
-      })
-    end
+      desc "Create a status."
+      params do
+        requires :status, :type => String, :desc => "Your status."
+      end
+      post do
+        authenticate!
+        Status.create!({
+          :user => current_user,
+          :text => params[:status]
+        })
+      end
 
-    desc "Update a status."
-    params do
-      requires :id, :type => String, :desc => "Status ID."
-      requires :status, :type => String, :desc => "Your status."
-    end
-    put ':id' do
-      authenticate!
-      current_user.statuses.find(params[:id]).update({
-        :user => current_user,
-        :text => params[:status]
-      })
-    end
+      desc "Update a status."
+      params do
+        requires :id, :type => String, :desc => "Status ID."
+        requires :status, :type => String, :desc => "Your status."
+      end
+      put ':id' do
+        authenticate!
+        current_user.statuses.find(params[:id]).update({
+          :user => current_user,
+          :text => params[:status]
+        })
+      end
 
-    desc "Delete a status."
-    params do
-      requires :id, :type => String, :desc => "Status ID."
-    end
-    delete ':id' do
-      authenticate!
-      current_user.statuses.find(params[:id]).destroy
-    end
+      desc "Delete a status."
+      params do
+        requires :id, :type => String, :desc => "Status ID."
+      end
+      delete ':id' do
+        authenticate!
+        current_user.statuses.find(params[:id]).destroy
+      end
 
+    end
   end
-
 end
 ```
 
@@ -120,7 +117,7 @@ end
 The above sample creates a Rack application that can be run from a rackup *config.ru* file
 with `rackup`:
 
-``` ruby
+```ruby
 run Twitter::API
 ```
 
@@ -137,8 +134,8 @@ And would respond to the following routes:
 
 In a Rails application, modify *config/routes*:
 
-``` ruby
-mount Twitter::API => "/"
+```ruby
+mount Twitter::API
 ```
 
 Note that when using Rails you will need to restart the server to pick up changes in your API classes
@@ -178,7 +175,7 @@ is returned when no correct `Accept` header is supplied.
 
 ### Path
 
-``` ruby
+```ruby
 version 'v1', :using => :path
 ```
 
@@ -209,7 +206,7 @@ version 'v1', :using => :param, :parameter => "v"
 
 You can add a description to API methods and namespaces.
 
-``` ruby
+```ruby
 desc "Returns your public timeline."
 get :public_timeline do
   Status.limit(20)
@@ -229,11 +226,13 @@ end
 
 Parameters are also populated from the request body on POST and PUT for JSON and XML content-types.
 
-The Request:
+The request:
 
-```curl -d '{"text": "140 characters"}' 'http://localhost:9292/statuses' -H Content-Type:application/json -v```
+```
+curl -d '{"text": "140 characters"}' 'http://localhost:9292/statuses' -H Content-Type:application/json -v
+```
 
-The Grape Endpoint:
+The Grape endpoint:
 
 ```ruby
 post '/statuses' do
@@ -343,15 +342,15 @@ Headers are available through the `header` helper or the `env` hash object.
 
 ```ruby
 get do
-    content_type = header['Content-type']
-    ...
+  content_type = header['Content-type']
+  # ...
 end
 ```
 
 ```ruby
 get do
-    error!('Unauthorized', 401) unless env['HTTP_SECRET_PASSWORD'] == 'swordfish'
-    ...
+  error!('Unauthorized', 401) unless env['HTTP_SECRET_PASSWORD'] == 'swordfish'
+  # ...
 end
 ```
 
@@ -371,7 +370,7 @@ end
 You can define helper methods that your endpoints can use with the `helpers`
 macro by either giving a block or a module.
 
-``` ruby
+```ruby
 module StatusHelpers
   def user_info(user)
     "#{user} has statused #{user.statuses} status(s)"
@@ -400,7 +399,7 @@ end
 
 You can set, get and delete your cookies very simply using `cookies` method.
 
-``` ruby
+```ruby
 class API < Grape::API
 
   get 'status_count' do
@@ -418,7 +417,7 @@ end
 
 Use a hash-based syntax to set more than one value.
 
-``` ruby
+```ruby
 cookies[:status_count] = {
     :value => 0,
     :expires => Time.tomorrow,
@@ -429,15 +428,27 @@ cookies[:status_count] = {
 cookies[:status_count][:value] +=1
 ```
 
+Delete a cookie with `delete`.
+
+```ruby
+cookies.delete :status_count
+```
+
+Specify an optional path.
+
+```ruby
+cookies.delete :status_count, :path => '/'
+```
+
 ## Redirecting
 
 You can redirect to a new url temporarily (302) or permanently (301).
 
-``` ruby
+```ruby
 redirect "/statuses"
 ```
 
-``` ruby
+```ruby
 redirect "/statuses", :permanent => true
 ```
 
@@ -447,7 +458,7 @@ When you add a route for a resource, a route for the HTTP OPTIONS
 method will also be added. The response to an OPTIONS request will
 include an "Allow" header listing the supported methods.
 
-``` ruby
+```ruby
 class API < Grape::API
 
   get '/rt_count' do
@@ -461,6 +472,7 @@ class API < Grape::API
     current_user.rt_count += params[:value].to_i
     { :rt_count => current_user.rt_count }
   end
+
 end
 ```
 
@@ -490,22 +502,22 @@ curl -X DELETE -v http://localhost:3000/rt_count/
 
 You can abort the execution of an API method by raising errors with `error!`.
 
-``` ruby
-error!("Access Denied", 401)
+```ruby
+error! "Access Denied", 401
 ```
 
 You can also return JSON formatted objects by raising error! and passing a hash
 instead of a message.
 
-``` ruby
-error!({ "error" => "unexpected error", "detail" => "missing widget" }, 500)
+```ruby
+error! { "error" => "unexpected error", "detail" => "missing widget" }, 500
 ```
 
 ## Exception Handling
 
-Grape can be told to rescue all exceptions and return them in txt or json formats.
+Grape can be told to rescue all exceptions and return them in the API format.
 
-``` ruby
+```ruby
 class Twitter::API < Grape::API
   rescue_from :all
 end
@@ -513,7 +525,7 @@ end
 
 You can also rescue specific exceptions.
 
-``` ruby
+```ruby
 class Twitter::API < Grape::API
   rescue_from ArgumentError, NotImplementedError
 end
@@ -523,7 +535,7 @@ The error format will match the request format. See "Content-Types" below.
 
 Custom error formatters for existing and additional types can be defined with a proc.
 
-``` ruby
+```ruby
 class Twitter::API < Grape::API
   error_formatter :txt, lambda { |message, backtrace, options, env|
     "error: #{message} from #{backtrace}"
@@ -533,7 +545,7 @@ end
 
 You can also use a module or class.
 
-``` ruby
+```ruby
 module CustomFormatter
   def self.call(message, backtrace, options, env)
     { message: message, backtrace: backtrace }
@@ -548,7 +560,7 @@ end
 You can rescue all exceptions with a code block. The `rack_response` wrapper
 automatically sets the default error code and content-type.
 
-``` ruby
+```ruby
 class Twitter::API < Grape::API
   rescue_from :all do |e|
     rack_response({ :message => "rescued from #{e.class.name}" })
@@ -559,7 +571,7 @@ end
 You can also rescue specific exceptions with a code block and handle the Rack
 response at the lowest level.
 
-``` ruby
+```ruby
 class Twitter::API < Grape::API
   rescue_from :all do |e|
     Rack::Response.new([ e.message ], 500, { "Content-type" => "text/error" }).finish
@@ -569,7 +581,7 @@ end
 
 Or rescue specific exceptions.
 
-``` ruby
+```ruby
 class Twitter::API < Grape::API
   rescue_from ArgumentError do |e|
     Rack::Response.new([ "ArgumentError: #{e.message}" ], 500)
@@ -588,7 +600,7 @@ class from Ruby's standard library.
 To log messages from within an endpoint, you need to define a helper to make the logger
 available in the endpoint context.
 
-``` ruby
+```ruby
 class API < Grape::API
   helpers do
     def logger
@@ -596,7 +608,7 @@ class API < Grape::API
     end
   end
   post '/statuses' do
-    ...
+    # ...
     logger.info "#{current_user} has statused"
   end
 end
@@ -604,7 +616,7 @@ end
 
 You can also set your own logger.
 
-``` ruby
+```ruby
 class MyLogger
   def warning(message)
     puts "this is a warning: #{message}"
@@ -624,10 +636,11 @@ class API < Grape::API
 end
 ```
 
-## Content-Types
+## API Formats
 
-By default, Grape supports _XML_, _JSON_, _Atom_, _RSS_, and _text_ content-types.
-Serialization takes place automatically.
+By default, Grape supports _XML_, _JSON_, and _TXT_ content-types. The default format is `:txt`. 
+
+Serialization takes place automatically. For example, you do not have to call `to_json` in each JSON API implementation.
 
 Your API can declare which types to support by using `content_type`. Response format
 is determined by the request's extension, an explicit `format` parameter in the query
@@ -636,16 +649,25 @@ string, or `Accept` header.
 The following API will only respond to the JSON content-type. All other requests will
 fail with an HTTP 406 error code.
 
-``` ruby
+```ruby
 class Twitter::API < Grape::API
   format :json
   content_type :json, "application/json"
 end
 ```
 
+If you combine `format` with `rescue_from :all`, errors will be rendered using the same format. If you do not want this behavior, set the default error formatter with `default_error_formatter`.
+
+```ruby
+class Twitter::API < Grape::API
+  format :json
+  default_error_formatter :txt
+end
+```
+
 Custom formatters for existing and additional types can be defined with a proc.
 
-``` ruby
+```ruby
 class Twitter::API < Grape::API
   content_type :xls, "application/vnd.ms-excel"
   formatter :xls, lambda { |object, env| object.to_xls }
@@ -654,7 +676,7 @@ end
 
 You can also use a module or class.
 
-``` ruby
+```ruby
 module XlsFormatter
   def self.call(object, env)
     object.to_xls
@@ -667,30 +689,22 @@ class Twitter::API < Grape::API
 end
 ```
 
-The default format is `:txt`. You can set the preferred format for an API that
-supports multiple formats with `format`.
+Built-in formats are the following.
 
-``` ruby
-class Twitter::API < Grape::API
-  format :json
-end
-```
+* `:json`: use object's `to_json` when available, otherwise call `MultiJson.dump`
+* `:xml`: use object's `to_xml` when available, usually via `MultiXml`, otherwise call `to_s`
+* `:txt`: use object's `to_txt` when available, otherwise `to_s`
+* `:serializable_hash`: use object's `serializable_hash` when available, otherwise fallback to `:json`
 
-You can set the fallback, default format with `default_format`.
+Use `default_format` to set the fallback format when the format could not be determined from the `Accept` header. 
+See below for the order for choosing the API format.
 
-``` ruby
+```ruby
 class Twitter::API < Grape::API
   default_format :json
 end
 ```
 
-Available formats are the following.
-
-* `:json`: use object's `to_json` when available, otherwise call `MultiJson.dump`
-* `:xml`: use object's `to_xml` when available, usually via `MultiXml`, otherwise call `to_s`
-* `:txt`: use object's `to_txt` when available, otherwise `to_s`
-* `:serializable_hash`: use object's `serializable_hash` when available, otherwise fallback to `:json`
-
 The order for choosing the format is the following.
 
 * Use the file extension, if specified. If the file is .json, choose the JSON format.
@@ -698,13 +712,14 @@ The order for choosing the format is the following.
 * Use the format set by the `format` option, if specified.
 * Attempt to find an acceptable format from the `Accept` header.
 * Use the default format, if specified by the `default_format` option.
-* Default to `:txt` otherwise.
+* Default to `:txt`.
 
 ## Content-type
 
-You can override the content-type of the response by setting the `Content-Type` header.
+Content-type is set by the formatter. You can override the content-type of the response at runtime
+by setting the `Content-Type` header.
 
-``` ruby
+```ruby
 class API < Grape::API
   get '/home_timeline_js' do
     content_type "application/javascript"
@@ -744,7 +759,7 @@ array.
     * expose the value returned by the block
     * block can only be applied to one exposure at a time
 
-``` ruby
+```ruby
 module API
   module Entities
     class Status < Grape::Entity
@@ -794,7 +809,7 @@ options hash must always include `:with`, which defines the entity to expose.
 
 If the entity includes documentation it can be included in an endpoint's description.
 
-``` ruby
+```ruby
 module API
   class Statuses < Grape::API
     version 'v1'
@@ -888,17 +903,19 @@ contains a `route_prefix`, `route_version`, `route_namespace`, `route_method`,
 follows the API path may contain any number of keys and its values are also
 accessible via dynamically-generated `route_[name]` functions.
 
-``` ruby
+```ruby
 TwitterAPI::versions # yields [ 'v1', 'v2' ]
 TwitterAPI::routes # yields an array of Grape::Route objects
 TwitterAPI::routes[0].route_version # yields 'v1'
 TwitterAPI::routes[0].route_description # etc.
 ```
 
+## Current Route and Endpoint
+
 It's possible to retrieve the information about the current route from within an API
 call with `route`.
 
-``` ruby
+```ruby
 class MyAPI < Grape::API
   desc "Returns a description of a parameter."
   params do
@@ -910,6 +927,21 @@ class MyAPI < Grape::API
 end
 ```
 
+The current endpoint responding to the request is `self` within the API block 
+or `env['api.endpoint']` elsewhere. The endpoint has some interesting properties, 
+such as `source` which gives you access to the original code block of the API 
+implementation. This can be particularly useful for building a logger middleware.
+
+```ruby
+class ApiLogger < Grape::Middleware::Base
+  def before
+    file = env['api.endpoint'].source.source_location[0]
+    line = env['api.endpoint'].source.source_location[1]
+    logger.debug "[api] #{file}:#{line}"
+  end
+end
+```
+
 ## Anchoring
 
 Grape by default anchors all request paths, which means that the request URL
@@ -922,7 +954,7 @@ In Grape this option can be used as well when a method is defined.
 
 For instance when you're API needs to get part of an URL, for instance:
 
-``` ruby
+```ruby
 class TwitterAPI < Grape::API
   namespace :statues do
     get '/(*:status)', :anchor => false do
@@ -962,7 +994,7 @@ describe Twitter::API do
       it "returns an empty array of statuses" do
         get "/api/v1/statuses"
         last_response.status.should == 200
-        JSON.parse(response.body).should == []
+        JSON.parse(last_response.body).should == []
       end
     end
     describe "GET /api/v1/statuses/:id" do
@@ -978,7 +1010,7 @@ end
 
 ### Writing Tests with Rails
 
-``` ruby
+```ruby
 require 'spec_helper'
 
 describe Twitter::API do
@@ -1009,6 +1041,9 @@ RSpec.configure do |config|
   }
 end
 ```
+## Performance Monitoring
+
+Grape integrates with NewRelic via the [newrelic-grape](https://github.com/flyerhzm/newrelic-grape) gem.
 
 ## Contributing to Grape
 
@@ -1018,7 +1053,7 @@ features and discuss issues.
 * Fork the project
 * Write tests for your new feature or a test that reproduces a bug
 * Implement your feature or make a bug fix
-* Do not mess with Rakefile, version or history
+* Add a line to `CHANGELOG.markdown` describing your change
 * Commit, push and make a pull request. Bonus points for topic branches.
 
 ## License