grape 0.4.1 → 0.5.0

data/CHANGELOG.md

@@ -1,8 +1,34 @@
+0.5.0 (6/14/2013)
+=================
+
+#### Features
+
+* [#344](https://github.com/intridea/grape/pull/344): Added `parser :type, nil` which disables input parsing for a given content-type - [@dblock](https://github.com/dblock).
+* [#381](https://github.com/intridea/grape/issues/381): Added `cascade false` option at API level to remove the `X-Cascade: true` header from the API response - [@dblock](https://github.com/dblock).
+* [#392](https://github.com/intridea/grape/pull/392): Extracted headers and params from `Endpoint` to `Grape::Request` - [@niedhui](https://github.com/niedhui).
+* [#376](https://github.com/intridea/grape/pull/376): Added `route_param`, syntax sugar for quick declaration of route parameters - [@mbleigh](https://github.com/mbleigh).
+* [#390](https://github.com/intridea/grape/pull/390): Added default value for an `optional` parameter - [@oivoodoo](https://github.com/oivoodoo).
+* [#403](https://github.com/intridea/grape/pull/403): Added support for versioning using the `Accept-Version` header - [@politician](https://github.com/politician).
+* [#407](https://github.com/intridea/grape/issues/407): Specifying `default_format` will also set the default POST/PUT data parser to the given format - [@dblock](https://github.com/dblock).
+* [#241](https://github.com/intridea/grape/issues/241): Present with multiple entities using an optional Symbol - [@niedhui](https://github.com/niedhui).
+
+#### Fixes
+
+* [#378](https://github.com/intridea/grape/pull/378): Fix: stop rescuing all exceptions during formatting - [@kbarrette](https://github.com/kbarrette).
+* [#380](https://github.com/intridea/grape/pull/380): Fix: `Formatter#read_body_input` when transfer encoding is chunked - [@paulnicholon](https://github.com/paulnicholson).
+* [#347](https://github.com/intridea/grape/issues/347): Fix: handling non-hash body params - [@paulnicholon](https://github.com/paulnicholson).
+* [#394](https://github.com/intridea/grape/pull/394): Fix: path version no longer overwrites a `version` parameter - [@tmornini](https://github.com/tmornini).
+* [#412](https://github.com/intridea/grape/issues/412): Fix: specifying `content_type` will also override the selection of the data formatter - [@dblock](https://github.com/dblock).
+* [#383](https://github.com/intridea/grape/issues/383): Fix: Mounted APIs aren't inheriting settings (including `before` and `after` filters) - [@seanmoon](https://github.com/seanmoon).
+* [#408](https://github.com/intridea/grape/pull/408): Fix: Goliath passes request header keys as symbols not strings - [@bobek](https://github.com/bobek).
+* [#417](https://github.com/intridea/grape/issues/417): Fix: Rails 4 does not rewind input, causes POSTed data to be empty - [@dblock](https://github.com/dblock).
+* [#423](https://github.com/intridea/grape/pull/423): Fix: `Grape::Endpoint#declared` now correctly handles nested params (ie. declared with `group`) - [@jbarreneche](https://github.com/jbarreneche).
+* [#427](https://github.com/intridea/grape/issues/427): Fix: `declared(params)` breaks when `params` contains array - [@timhabermaas](https://github.com/timhabermaas)
+
 0.4.1 (4/1/2013)
 ================
 
 * [#375](https://github.com/intridea/grape/pull/375): Fix: throwing an `:error` inside a middleware doesn't respect the `format` settings - [@dblock](https://github.com/dblock).
-* Your contribution here.
 
 0.4.0 (3/17/2013)
 =================
@@ -101,8 +127,7 @@
 0.2.2
 =====
 
-Features
---------
+#### Features
 
 * [#201](https://github.com/intridea/grape/pull/201), [#236](https://github.com/intridea/grape/pull/236), [#221](https://github.com/intridea/grape/pull/221): Added coercion and validations support to `params` DSL - [@schmurfy](https://github.com/schmurfy), [@tim-vandecasteele](https://github.com/tim-vandecasteele), [@adamgotterer](https://github.com/adamgotterer).
 * [#204](https://github.com/intridea/grape/pull/204): Added ability to declare shared `params` at `namespace` level - [@tim-vandecasteele](https://github.com/tim-vandecasteele).
@@ -110,8 +135,7 @@ Features
 * [#240](https://github.com/intridea/grape/pull/240): Define API response format from a query string `format` parameter, if specified - [@neetiraj](https://github.com/neetiraj).
 * Adds Endpoint#declared to easily filter out unexpected params. - [@mbleigh](https://github.com/mbleigh)
 
-Fixes
------
+#### Fixes
 
 * [#248](https://github.com/intridea/grape/pull/248): Fix: API `version` returns last version set - [@narkoz](https://github.com/narkoz).
 * [#242](https://github.com/intridea/grape/issues/242): Fix: permanent redirect status should be `301`, was `304` - [@adamgotterer](https://github.com/adamgotterer).

data/Gemfile

@@ -15,4 +15,5 @@ group :development, :test do
   gem 'github-markup'
   gem 'cookiejar'
   gem 'rack-contrib'
+  gem 'redcarpet', :platforms => :ruby
 end

data/README.md

@@ -10,13 +10,9 @@ content negotiation, versioning and much more.
 
 [![Build Status](https://travis-ci.org/intridea/grape.png?branch=master)](http://travis-ci.org/intridea/grape) [![Code Climate](https://codeclimate.com/github/intridea/grape.png)](https://codeclimate.com/github/intridea/grape)
 
-## Stable Release
+## Project Resources
 
-You're reading the documentation for the stable 0.4.1 release of Grape.
-
-## Project Tracking
-
-* [Grape Google Group](http://groups.google.com/group/ruby-grape)
+* Need help? [Grape Google Group](http://groups.google.com/group/ruby-grape)
 * [Grape Wiki](https://github.com/intridea/grape/wiki)
 
 ## Installation
@@ -41,7 +37,7 @@ the context of recreating parts of the Twitter API.
 module Twitter
   class API < Grape::API
 
-    version 'v1', :using => :header, :vendor => 'twitter'
+    version 'v1', using: :header, vendor: 'twitter'
     format :json
 
     helpers do
@@ -69,40 +65,42 @@ module Twitter
 
       desc "Return a status."
       params do
-        requires :id, :type => Integer, :desc => "Status id."
+        requires :id, type: Integer, desc: "Status id."
       end
-      get ':id' do
-        Status.find(params[:id])
+      route_param :id do
+        get do
+          Status.find(params[:id])
+        end
       end
 
       desc "Create a status."
       params do
-        requires :status, :type => String, :desc => "Your status."
+        requires :status, type: String, desc: "Your status."
       end
       post do
         authenticate!
         Status.create!({
-          :user => current_user,
-          :text => params[:status]
+          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."
+        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]
+          user: current_user,
+          text: params[:status]
         })
       end
 
       desc "Delete a status."
       params do
-        requires :id, :type => String, :desc => "Status ID."
+        requires :id, type: String, desc: "Status ID."
       end
       delete ':id' do
         authenticate!
@@ -136,12 +134,39 @@ And would respond to the following routes:
 
 Grape will also automatically respond to HEAD and OPTIONS for all GET, and just OPTIONS for all other routes.
 
+### Alongside Sinatra (or other frameworks)
+
+If you wish to mount Grape alongside another Rack framework such as Sinatra, you can do so easily using
+`Rack::Cascade`:
+
+```ruby
+# Example config.ru
+
+require 'sinatra'
+require 'grape'
+
+class API < Grape::API
+  get :hello do
+    {hello: "world"}
+  end
+end
+
+class Web < Sinatra::Base
+  get '/' do
+    "Hello world."
+  end
+end
+
+use Rack::Session::Cookie
+run Rack::Cascade.new [API, Web]
+```
+
 ### Rails
 
 Place API files into `app/api` and modify `application.rb`.
 
 ```ruby
-config.paths.add "app/api", :glob => "**/*.rb"
+config.paths.add "app/api", glob: "**/*.rb"
 config.autoload_paths += Dir["#{Rails.root}/app/api/*"]
 ```
 
@@ -175,13 +200,13 @@ end
 
 ## Versioning
 
-There are three strategies in which clients can reach your API's endpoints: `:path`,
-`:header` and `:param`. The default strategy is `:path`.
+There are four strategies in which clients can reach your API's endpoints: `:path`,
+`:header`, `:accept_version_header` and `:param`. The default strategy is `:path`.
 
 ### Path
 
 ```ruby
-version 'v1', :using => :path
+version 'v1', using: :path
 ```
 
 Using this versioning strategy, clients should pass the desired version in the URL.
@@ -191,7 +216,7 @@ Using this versioning strategy, clients should pass the desired version in the U
 ### Header
 
 ```ruby
-version 'v1', :using => :header, :vendor => 'twitter'
+version 'v1', using: :header, vendor: 'twitter'
 ```
 
 Using this versioning strategy, clients should pass the desired version in the HTTP `Accept` head.
@@ -203,10 +228,25 @@ supplied. This behavior is similar to routing in Rails. To circumvent this defau
 one could use the `:strict` option. When this option is set to `true`, a `406 Not Acceptable` error
 is returned when no correct `Accept` header is supplied.
 
+### Accept-Version Header
+
+```ruby
+version 'v1', using: :accept_version_header
+```
+
+Using this versioning strategy, clients should pass the desired version in the HTTP `Accept-Version` header.
+
+    curl -H "Accept-Version=v1" http://localhost:9292/statuses/public_timeline
+
+By default, the first matching version is used when no `Accept-Version` header is
+supplied. This behavior is similar to routing in Rails. To circumvent this default behavior,
+one could use the `:strict` option. When this option is set to `true`, a `406 Not Acceptable` error
+is returned when no correct `Accept` header is supplied.
+
 ### Param
 
 ```ruby
-version 'v1', :using => :param
+version 'v1', using: :param
 ```
 
 Using this versioning strategy, clients should pass the desired version as a request parameter,
@@ -217,7 +257,7 @@ either in the URL query string or in the request body.
 The default name for the query parameter is 'apiver' but can be specified using the `:parameter` option.
 
 ```ruby
-version 'v1', :using => :param, :parameter => "v"
+version 'v1', using: :param, parameter: "v"
 ```
 
     curl -H http://localhost:9292/statuses/public_timeline?v=v1
@@ -258,7 +298,7 @@ The Grape endpoint:
 
 ```ruby
 post '/statuses' do
-  Status.create!({ :text => params[:text] })
+  Status.create!({ text: params[:text] })
 end
 ```
 
@@ -298,6 +338,14 @@ end
 When a type is specified an implicit validation is done after the coercion to ensure
 the output type is the one declared.
 
+Optional parameters can have a default value.
+
+```ruby
+params do
+  optional :color, type: String, default: 'blue'
+end
+```
+
 Parameters can be nested using `group`. In the above example, this means
 `params[:media][:url]` is required along with `params[:id]`.
 
@@ -331,7 +379,7 @@ The `namespace` method has a number of aliases, including: `group`, `resource`,
 class AlphaNumeric < Grape::Validations::Validator
   def validate_param!(attr_name, params)
     unless params[attr_name] =~ /^[[:alnum:]]+$/
-      throw :error, :status => 400, :message => "#{attr_name}: must consist of alpha-numeric characters"
+      throw :error, status: 400, message: "#{attr_name}: must consist of alpha-numeric characters"
     end
   end
 end
@@ -339,7 +387,7 @@ end
 
 ```ruby
 params do
-  requires :text, :alpha_numeric => true
+  requires :text, alpha_numeric: true
 end
 ```
 
@@ -349,7 +397,7 @@ You can also create custom classes that take parameters.
 class Length < Grape::Validations::SingleOptionValidator
   def validate_param!(attr_name, params)
     unless params[attr_name].length <= @option
-      throw :error, :status => 400, :message => "#{attr_name}: must be at the most #{@option} characters long"
+      throw :error, status: 400, message: "#{attr_name}: must be at the most #{@option} characters long"
     end
   end
 end
@@ -357,7 +405,7 @@ end
 
 ```ruby
 params do
-  requires :text, :length => 140
+  requires :text, length: 140
 end
 ```
 
@@ -405,11 +453,11 @@ Optionally, you can define requirements for your named route parameters using re
 expressions on namespace or endpoint. The route will match only if all requirements are met.
 
 ```ruby
-get ':id', :requirements => { :id => /[0-9]*/ } do
+get ':id', requirements: { id: /[0-9]*/ } do
   Status.find(params[:id])
 end
 
-namespace :outer, :requirements => { :id => /[0-9]*/ } do
+namespace :outer, requirements: { id: /[0-9]*/ } do
   get :id do
   end
 
@@ -458,11 +506,11 @@ class API < Grape::API
   get 'status_count' do
     cookies[:status_count] ||= 0
     cookies[:status_count] += 1
-    { :status_count => cookies[:status_count] }
+    { status_count: cookies[:status_count] }
   end
 
   delete 'status_count' do
-    { :status_count => cookies.delete(:status_count) }
+    { status_count: cookies.delete(:status_count) }
   end
 
 end
@@ -472,10 +520,10 @@ Use a hash-based syntax to set more than one value.
 
 ```ruby
 cookies[:status_count] = {
-    :value => 0,
-    :expires => Time.tomorrow,
-    :domain => '.twitter.com',
-    :path => '/'
+    value: 0,
+    expires: Time.tomorrow,
+    domain: '.twitter.com',
+    path: '/'
 }
 
 cookies[:status_count][:value] +=1
@@ -490,7 +538,7 @@ cookies.delete :status_count
 Specify an optional path.
 
 ```ruby
-cookies.delete :status_count, :path => '/'
+cookies.delete :status_count, path: '/'
 ```
 
 ## Redirecting
@@ -502,7 +550,7 @@ redirect "/statuses"
 ```
 
 ```ruby
-redirect "/statuses", :permanent => true
+redirect "/statuses", permanent: true
 ```
 
 ## Allowed Methods
@@ -531,15 +579,15 @@ include an "Allow" header listing the supported methods.
 class API < Grape::API
 
   get '/rt_count' do
-    { :rt_count => current_user.rt_count }
+    { rt_count: current_user.rt_count }
   end
 
   params do
-    requires :value, :type => Integer, :desc => 'Value to add to the rt count.'
+    requires :value, type: Integer, desc: 'Value to add to the rt count.'
   end
   put '/rt_count' do
     current_user.rt_count += params[:value].to_i
-    { :rt_count => current_user.rt_count }
+    { rt_count: current_user.rt_count }
   end
 
 end
@@ -634,7 +682,7 @@ automatically sets the default error code and content-type.
 ```ruby
 class Twitter::API < Grape::API
   rescue_from :all do |e|
-    rack_response({ :message => "rescued from #{e.class.name}" })
+    rack_response({ message: "rescued from #{e.class.name}" })
   end
 end
 ```
@@ -665,19 +713,23 @@ end
 
 #### Rails 3.x
 
-When mounted inside Rails 3.x, errors like "404 Not Found" or "406 Not Acceptable" will likely be
-handled and rendered by Rails handlers. For instance, accessing a nonexistent route "/api/foo"
-raises a 404, which inside rails will ultimately be translated to an `ActionController::RoutingError`,
-which most likely will get rendered to a HTML error page.
+When mounted inside containers, such as Rails 3.x, errors like "404 Not Found" or
+"406 Not Acceptable" will likely be handled and rendered by Rails handlers. For instance,
+accessing a nonexistent route "/api/foo" raises a 404, which inside rails will ultimately
+be translated to an `ActionController::RoutingError`, which most likely will get rendered
+to a HTML error page.
 
-Most APIs will enjoy avoiding Rails exceptions and have their own exceptions reaching the client.
-In that case, the `:cascade` option can be set to `false` on the versioning definition.
+Most APIs will enjoy preventing downstream handlers from handling errors. You may set the
+`:cascade` option to `false` for the entire API or separately on specific `version` definitions,
+which will remove the `X-Cascade: true` header from API responses.
 
 ```ruby
-version 'v1', :using => :header, :vendor => 'twitter', :cascade => false
+cascade false
 ```
 
-The `:cascade` option can also be used with the other versioning strategies (`:param` and `:path`).
+```ruby
+version 'v1', using: :header, vendor: 'twitter', cascade: false
+```
 
 ## Logging
 
@@ -742,6 +794,16 @@ class Twitter::API < Grape::API
 end
 ```
 
+When the content-type is omitted, Grape will return a 406 error code unless `default_format` is specified.
+The following API will try to parse any data without a content-type using a JSON parser.
+
+```ruby
+class Twitter::API < Grape::API
+  format :json
+  default_format :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`.
 
@@ -822,23 +884,21 @@ end
 ### CORS
 
 Grape supports CORS via [Rack::CORS](https://github.com/cyu/rack-cors), part of the
-[rack-cors](https://github.com/cyu/rack-cors) gem. Add `rack-cors` to your `Gemfile`.
+[rack-cors](https://github.com/cyu/rack-cors) gem. Add `rack-cors` to your `Gemfile`,
+then use the middleware in your config.ru file.
 
 ```ruby
 require 'rack/cors'
 
-class API < Grape::API
-  use Rack::Cors do
-    allow do
-      origins '*'
-      resource '*', :headers => :any, :methods => :get
-    end
-  end
-  format :json
-  get '/' do
-    'Hello World'
+use Rack::Cors do
+  allow do
+    origins '*'
+    resource '*', headers: :any, methods: :get
   end
 end
+
+run Twitter::API
+
 ```
 
 ## Content-type
@@ -871,7 +931,7 @@ to `:value`. The parameter will be available via `params[:value]` inside the API
 ```ruby
 module CustomParser
   def self.call(object, env)
-    { :value => object.to_s }
+    { value: object.to_s }
   end
 end
 ```
@@ -892,6 +952,8 @@ You can invoke the above API as follows.
 curl -X PUT -d 'data' 'http://localhost:9292/value' -H Content-Type:text/custom -v
 ```
 
+You can disable parsing for a content-type with `nil`. For example, `parser :json, nil` will disable JSON parsing altogether. The request data is then available as-is in `env['api.request.body']`.
+
 ## RESTful Model Representations
 
 Grape supports a range of ways to present your data with some help from a generic `present` method,
@@ -900,8 +962,8 @@ hash may include `:with`, which defines the entity to expose.
 
 ### Grape Entities
 
-Add the [grape-entity](https://github.com/agileanimal/grape-entity) gem to your Gemfile.
-Please refer to the [grape-entity documentation](https://github.com/agileanimal/grape-entity/blob/master/README.markdown)
+Add the [grape-entity](https://github.com/intridea/grape-entity) gem to your Gemfile.
+Please refer to the [grape-entity documentation](https://github.com/intridea/grape-entity/blob/master/README.markdown)
 for more details.
 
 The following example exposes statuses.
@@ -912,11 +974,11 @@ module API
   module Entities
     class Status < Grape::Entity
       expose :user_name
-      expose :text, :documentation => { :type => "string", :desc => "Status update text." }
-      expose :ip, :if => { :type => :full }
-      expose :user_type, user_id, :if => lambda{ |status, options| status.user.public? }
+      expose :text, documentation: { type: "string", desc: "Status update text." }
+      expose :ip, if: { type: :full }
+      expose :user_type, user_id, if: lambda{ |status, options| status.user.public? }
       expose :digest { |status, options| Digest::MD5.hexdigest(status.txt) }
-      expose :replies, :using => API::Status, :as => :replies
+      expose :replies, using: API::Status, as: :replies
     end
   end
 
@@ -924,17 +986,38 @@ module API
     version 'v1'
 
     desc 'Statuses index', {
-      :object_fields => API::Entities::Status.documentation
+      object_fields: API::Entities::Status.documentation
     }
     get '/statuses' do
       statuses = Status.all
       type = current_user.admin? ? :full : :default
-      present statuses, with: API::Entities::Status, :type => type
+      present statuses, with: API::Entities::Status, type: type
     end
   end
 end
 ```
 
+You can present with multiple entities using an optional Symbol argument.
+
+```ruby
+  get '/statuses' do
+    statuses = Status.all.page(1).per(20)
+    present :total_page, 10
+    present :per_page, 20
+    present :statuses, statuses, with: API::Entities::Status
+  end
+```
+
+The response will be
+
+```
+  {
+    total_page: 10,
+    per_page: 20,
+    statuses: []
+  }
+```
+
 In addition to separately organizing entities, it may be useful to put them as namespaced
 classes underneath the model they represent.
 
@@ -982,7 +1065,7 @@ end
 ```
 
 ```ruby
-http_digest({ :realm => 'Test Api', :opaque => 'app secret' }) do |username|
+http_digest({ realm: 'Test Api', opaque: 'app secret' }) do |username|
   # lookup the user's password here
   { 'user1' => 'password1' }[username]
 end
@@ -1017,7 +1100,7 @@ call with `route`.
 class MyAPI < Grape::API
   desc "Returns a description of a parameter."
   params do
-    requires :id, :type => Integer, :desc => "Identity."
+    requires :id, type: Integer, desc: "Identity."
   end
   get "params/:id" do
     route.route_params[params[:id]] # yields the parameter description
@@ -1057,7 +1140,7 @@ should match from start to end to match, otherwise a `404 Not Found` is
 returned. However, this is sometimes not what you want, because it is not always
 known upfront what can be expected from the call. This is because Rack-mount by
 default anchors requests to match from the start to the end, or not at all.
-Rails solves this problem by using a `:anchor => false` option in your routes.
+Rails solves this problem by using a `anchor: false` option in your routes.
 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:
@@ -1065,7 +1148,7 @@ For instance when you're API needs to get part of an URL, for instance:
 ```ruby
 class TwitterAPI < Grape::API
   namespace :statuses do
-    get '/(*:status)', :anchor => false do
+    get '/(*:status)', anchor: false do
 
     end
   end
@@ -1144,8 +1227,8 @@ In Rails, HTTP request tests would go into the `spec/requests` group. You may wa
 
 ```ruby
 RSpec.configure do |config|
-  config.include RSpec::Rails::RequestExampleGroup, :type => :request, :example_group => {
-    :file_path => /spec\/api/
+  config.include RSpec::Rails::RequestExampleGroup, type: :request, example_group: {
+    file_path: /spec\/api/
   }
 end
 ```
@@ -1158,7 +1241,7 @@ Add API paths to `config/application.rb`.
 
 ```ruby
 # Auto-load API and its subdirectories
-config.paths.add "app/api", :glob => "**/*.rb"
+config.paths.add "app/api", glob: "**/*.rb"
 config.autoload_paths += Dir["#{Rails.root}/app/api/*"]
 ```
 
@@ -1166,6 +1249,9 @@ Create `config/initializers/reload_api.rb`.
 
 ```ruby
 if Rails.env.development?
+
+  ActiveSupport::Dependencies.explicitly_unloadable_constants << "Twitter::API"
+
   api_files = Dir["#{Rails.root}/app/api/**/*.rb"]
   api_reloader = ActiveSupport::FileUpdateChecker.new(api_files) do
     Rails.application.reload_routes!
@@ -1173,6 +1259,7 @@ if Rails.env.development?
   ActionDispatch::Callbacks.to_prepare do
     api_reloader.execute_if_updated
   end
+
 end
 ```
 
@@ -1181,7 +1268,9 @@ See [StackOverflow #3282655](http://stackoverflow.com/questions/3282655/ruby-on-
 
 ## Performance Monitoring
 
-Grape integrates with NewRelic via the [newrelic-grape](https://github.com/flyerhzm/newrelic-grape) gem.
+Grape integrates with NewRelic via the
+[newrelic-grape](https://github.com/flyerhzm/newrelic-grape) gem, and
+with Librato Metrics with the [grape-librato](https://github.com/seanmoon/grape-librato) gem.
 
 ## Contributing to Grape