grape 0.2.6 → 0.3.0

data/{CHANGELOG.markdown → CHANGELOG.md}

@@ -1,3 +1,23 @@
+0.3.0 (02/21/2013)
+==================
+
+* [#294](https://github.com/intridea/grape/issues/294): Extracted `Grape::Entity` into a [grape-entity](https://github.com/agileanimal/grape-entity) gem - [@agileanimal](https://github.com/agileanimal).
+* [#340](https://github.com/intridea/grape/pull/339), [#342](https://github.com/intridea/grape/pull/342): Added `:cascade` option to `version` to allow disabling of rack/mount cascade behavior - [@dieb](https://github.com/dieb).
+* [#333](https://github.com/intridea/grape/pull/333): Added support for validation of arrays in `params` - [@flyerhzm](https://github.com/flyerhzm).
+* [#306](https://github.com/intridea/grape/issues/306): Added I18n support for all Grape exceptions - [@niedhui](https://github.com/niedhui).
+* [#309](https://github.com/intridea/grape/pull/309): Added XML support to the entity presenter - [@johnnyiller](https://github.com/johnnyiller), [@dblock](http://github.com/dblock).
+* [#131](https://github.com/intridea/grape/issues/131): Added instructions for Grape API reloading in Rails - [@jyn](http://github.com/jyn), [@dblock](http://github.com/dblock).
+* [#317](https://github.com/intridea/grape/issues/317): Added `headers` that returns a hash of parsed HTTP request headers - [@dblock](http://github.com/dblock).
+* [#332](https://github.com/intridea/grape/pull/332): `Grape::Exceptions::Validation` now contains full nested parameter names - [@alovak](https://github.com/alovak).
+* [#328](https://github.com/intridea/grape/issues/328): API version can now be specified as both String and Symbol - [@dblock](http://github.com/dblock).
+* [#190](https://github.com/intridea/grape/issues/190): When you add a `GET` route for a resource, a route for the `HEAD` method will also be added automatically. You can disable this behavior with `do_not_route_head!` - [@dblock](http://github.com/dblock).
+* Added `do_not_route_options!`, which disables the automatic creation of the `OPTIONS` route - [@dblock](http://github.com/dblock).
+* [#309](https://github.com/intridea/grape/pull/309): An XML format API will return an error instead of returning a string representation of the response if the latter cannot be converted to XML - [@dblock](http://github.com/dblock).
+* A formatter that raises an exception will cause the API to return a 500 error - [@dblock](http://github.com/dblock).
+* [#322](https://github.com/intridea/grape/issues/322): When returning a 406 status, Grape will include the requested format or content-type in the response body - [@dblock](http://github.com/dblock).
+* [#60](https://github.com/intridea/grape/issues/60): Fix: mounting of a Grape API onto a path - [@dblock](http://github.com/dblock).
+* [#335](https://github.com/intridea/grape/pull/335): Fix: request body parameters from a `PATCH` request not available in `params` - [@FreakenK](http://github.com/FreakenK).
+
 0.2.6 (01/11/2013)
 ==================
 
@@ -77,7 +97,7 @@ Fixes
 
 * [#186](https://github.com/intridea/grape/issues/186): Fix: helpers allow multiple calls with modules and blocks - [@ppadron](https://github.com/ppadron).
 * [#188](https://github.com/intridea/grape/pull/188): Fix: multi-method routes append '(.:format)' only once - [@kainosnoema](https://github.com/kainosnoema).
-* [#64](https://github.com/intridea/grape/issues/64), [#180](https://github.com/intridea/grape/pull/180): Added support to get request bodies as parameters - [@bobbytables](https://github.com/bobbytables).
+* [#64](https://github.com/intridea/grape/issues/64), [#180](https://github.com/intridea/grape/pull/180): Added support to `GET` request bodies as parameters - [@bobbytables](https://github.com/bobbytables).
 * [#175](https://github.com/intridea/grape/pull/175): Added support for API versioning based on a request parameter - [@jackcasey](https://github.com/jackcasey).
 * [#168](https://github.com/intridea/grape/pull/168): Fix: Formatter can parse symbol keys in the headers hash - [@netmask](https://github.com/netmask).
 * [#169](https://github.com/intridea/grape/pull/169): Silence multi_json deprecation warnings - [@whiteley](https://github.com/whiteley).

data/Gemfile

@@ -13,4 +13,5 @@ group :development, :test do
   gem 'rspec'
   gem 'rack-test', "~> 0.6.2", :require => "rack/test"
   gem 'github-markup'
+  gem 'cookiejar'
 end

data/{README.markdown → README.md}

@@ -10,6 +10,11 @@ content negotiation, versioning and much more.
 
 [![Build Status](https://travis-ci.org/intridea/grape.png?branch=master)](http://travis-ci.org/intridea/grape)
 
+## Stable Release
+
+You're reading the documentation for the next release of Grape, which should be 0.3.
+The current stable release is [0.2.6](https://github.com/intridea/grape/blob/v0.2.6/README.markdown).
+
 ## Project Tracking
 
 * [Grape Google Group](http://groups.google.com/group/ruby-grape)
@@ -114,7 +119,7 @@ end
 
 ### Rack
 
-The above sample creates a Rack application that can be run from a rackup *config.ru* file
+The above sample creates a Rack application that can be run from a rackup `config.ru` file
 with `rackup`:
 
 ```ruby
@@ -130,16 +135,24 @@ And would respond to the following routes:
     PUT /statuses/:id(.json)
     DELETE /statuses/:id(.json)
 
+Grape will also automatically respond to HEAD and OPTIONS for all GET, and just OPTIONS for all other routes.
+
 ### Rails
 
-In a Rails application, modify *config/routes*:
+Place API files into `app/api` and modify `application.rb`.
 
 ```ruby
-mount Twitter::API
+config.paths.add "app/api", :glob => "**/*.rb"
+config.autoload_paths += Dir["#{Rails.root}/app/api/*"]
 ```
 
-Note that when using Rails you will need to restart the server to pick up changes in your API classes
-(see [Issue 131](https://github.com/intridea/grape/issues/131)).
+Modify `config/routes`:
+
+```ruby
+mount Twitter::API => '/'
+```
+
+See below for additional code that enables reloading of API changes in development.
 
 ### Modules
 
@@ -153,10 +166,28 @@ class Twitter::API < Grape::API
 end
 ```
 
+You can also mount on a path, which is similar to using `prefix` inside the mounted API itself.
+
+```ruby
+class Twitter::API < Grape::API
+  mount Twitter::APIv1 => '/v1'
+end
+```
+
 ## Versioning
 
-There are three strategies in which clients can reach your API's endpoints: `:header`,
-`:path` and `:param`. The default strategy is `:path`.
+There are three strategies in which clients can reach your API's endpoints: `:path`,
+`:header` and `:param`. The default strategy is `:path`.
+
+### Path
+
+```ruby
+version 'v1', :using => :path
+```
+
+Using this versioning strategy, clients should pass the desired version in the URL.
+
+    curl -H http://localhost:9292/v1/statuses/public_timeline
 
 ### Header
 
@@ -173,16 +204,6 @@ 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.
 
-### Path
-
-```ruby
-version 'v1', :using => :path
-```
-
-Using this versioning strategy, clients should pass the desired version in the URL.
-
-    curl -H http://localhost:9292/v1/statuses/public_timeline
-
 ### Param
 
 ```ruby
@@ -202,6 +223,7 @@ version 'v1', :using => :param, :parameter => "v"
 
     curl -H http://localhost:9292/statuses/public_timeline?v=v1
 
+
 ## Describing Methods
 
 You can add a description to API methods and namespaces.
@@ -241,6 +263,22 @@ post '/statuses' do
 end
 ```
 
+Multipart POSTs and PUTs are supported as well.
+
+The request:
+
+```
+curl --form image_file=image.jpg http://localhost:9292/upload
+```
+
+The Grape endpoint:
+
+```ruby
+post "upload" do
+  # file in params[:image_file]
+end
+```
+
 ## Parameter Validation and Coercion
 
 You can define validations and coercion options for your parameters using a `params` block.
@@ -285,6 +323,9 @@ namespace :statuses do
 end
 ```
 
+The `namespace` method has a number of aliases, including: `group`, `resource`,
+`resources`, and `segment`. Use whichever reads the best for your API.
+
 ### Custom Validators
 
 ```ruby
@@ -339,22 +380,26 @@ end
 
 ## Headers
 
-Headers are available through the `header` helper or the `env` hash object.
+Request headers are available through the `headers` helper or from `env` in their original form.
 
 ```ruby
 get do
-  content_type = header['Content-type']
-  # ...
+  error!('Unauthorized', 401) unless headers['Secret-Password'] == 'swordfish'
 end
 ```
 
 ```ruby
 get do
   error!('Unauthorized', 401) unless env['HTTP_SECRET_PASSWORD'] == 'swordfish'
-  # ...
 end
 ```
 
+You can set a response header with `header` inside an API.
+
+```ruby
+header "X-Robots-Tag", "noindex"
+```
+
 ## Routes
 
 Optionally, you can define requirements for your named route parameters using regular
@@ -455,7 +500,23 @@ redirect "/statuses", :permanent => true
 
 ## Allowed Methods
 
-When you add a route for a resource, a route for the HTTP OPTIONS
+When you add a `GET` route for a resource, a route for the `HEAD`
+method will also be added automatically. You can disable this
+behavior with `do_not_route_head!`.
+
+``` ruby
+class API < Grape::API
+
+  do_not_route_head!
+
+  get '/example' do
+    # only responds to GET
+  end
+
+end
+```
+
+When you add a route for a resource, a route for the `OPTIONS`
 method will also be added. The response to an OPTIONS request will
 include an "Allow" header listing the supported methods.
 
@@ -486,6 +547,8 @@ curl -v -X OPTIONS http://localhost:3000/rt_count
 < Allow: OPTIONS, GET, PUT
 ```
 
+You can disable this behavior with `do_not_route_options!`.
+
 If a request for a resource is made with an unsupported HTTP method, an
 HTTP 405 (Method Not Allowed) response will be returned.
 
@@ -593,6 +656,22 @@ class Twitter::API < Grape::API
 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.
+
+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.
+
+```ruby
+version 'v1', :using => :header, :vendor => 'twitter', :cascade => false
+```
+
+The `:cascade` option can also be used with the other versioning strategies (`:param` and `:path`).
+
 ## Logging
 
 `Grape::API` provides a `logger` method which by default will return an instance of the `Logger`
@@ -648,7 +727,7 @@ is determined by the request's extension, an explicit `format` parameter in the
 string, or `Accept` header.
 
 The following API will only respond to the JSON content-type and will not parse any other input than `application/json`,
-'application/x-www-form-urlencoded', 'multipart/form-data', 'multipart/related' and 'multipart/mixed'. All other requests
+`application/x-www-form-urlencoded`, `multipart/form-data`, `multipart/related` and `multipart/mixed`. All other requests
 will fail with an HTTP 406 error code.
 
 ```ruby
@@ -767,89 +846,34 @@ You can invoke the above API as follows.
 curl -X PUT -d 'data' 'http://localhost:9292/value' -H Content-Type:text/custom -v
 ```
 
-## Reusable Responses with Entities
+## RESTful Model Representations
 
-Entities are a reusable means for converting Ruby objects to API responses.
-Entities can be used to conditionally include fields, nest other entities, and build
-ever larger responses, using inheritance.
+Grape supports a range of ways to present your data with some help from a generic `present` method,
+which accepts two arguments: the object to be presented and the options associated with it. The options
+hash may include `:with`, which defines the entity to expose.
 
-### Defining Entities
+### Grape Entities
 
-Entities inherit from Grape::Entity, and define a simple DSL. Exposures can use
-runtime options to determine which fields should be visible, these options are
-available to `:if`, `:unless`, and `:proc`. The option keys `:version` and `:collection`
-will always be defined. The `:version` key is defined as `api.version`. The
-`:collection` key is boolean, and defined as `true` if the object presented is an
-array.
+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)
+for more details.
 
-  * `expose SYMBOLS`
-    * define a list of fields which will always be exposed
-  * `expose SYMBOLS, HASH`
-    * HASH keys include `:if`, `:unless`, `:proc`, `:as`, `:using`, `:format_with`, `:documentation`
-      * `:if` and `:unless` accept hashes (passed during runtime) or procs (arguments are object and options)
-  * `expose SYMBOL, { :format_with => :formatter }`
-    * expose a value, formatting it first
-    * `:format_with` can only be applied to one exposure at a time
-  * `expose SYMBOL, { :as => "alias" }`
-    * Expose a value, changing its hash key from SYMBOL to alias
-    * `:as` can only be applied to one exposure at a time
-  * `expose SYMBOL BLOCK`
-    * block arguments are object and options
-    * expose the value returned by the block
-    * block can only be applied to one exposure at a time
+The following example exposes statuses.
 
 ```ruby
 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 :digest { |status, options| Digest::MD5.hexdigest(satus.txt) }
+      expose :digest { |status, options| Digest::MD5.hexdigest(status.txt) }
       expose :replies, :using => API::Status, :as => :replies
     end
   end
-end
-
-module API
-  module Entities
-    class StatusDetailed < API::Entities::Status
-      expose :internal_id
-    end
-  end
-end
-```
-
-#### Using the Exposure DSL
-
-Grape ships with a DSL to easily define entities within the context
-of an existing class:
-
-```ruby
-class Status
-  include Grape::Entity::DSL
-
-  entity :text, :user_id do
-    expose :detailed, if: :conditional
-  end
-end
-```
-
-The above will automatically create a `Status::Entity` class and define properties on it according
-to the same rules as above. If you only want to define simple exposures you don't have to supply
-a block and can instead simply supply a list of comma-separated symbols.
-
-### Using Entities
 
-Once an entity is defined, it can be used within endpoints, by calling `present`. The `present`
-method accepts two arguments, the object to be presented and the options associated with it. The
-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
-module API
   class Statuses < Grape::API
     version 'v1'
 
@@ -865,8 +889,6 @@ module API
 end
 ```
 
-### Entity Organization
-
 In addition to separately organizing entities, it may be useful to put them as namespaced
 classes underneath the model they represent.
 
@@ -883,53 +905,44 @@ end
 ```
 
 If you organize your entities this way, Grape will automatically detect the `Entity` class and
-use it to present your models. In this example, if you added `present User.new` to your endpoint,
-Grape would automatically detect that there is a `Status::Entity` class and use that as the
+use it to present your models. In this example, if you added `present Status.new` to your endpoint,
+Grape will automatically detect that there is a `Status::Entity` class and use that as the
 representative entity. This can still be overridden by using the `:with` option or an explicit
 `represents` call.
 
-### Caveats
+### Hypermedia
+
+You can use any Hypermedia representer, including [Roar](https://github.com/apotonick/roar).
+Roar renders JSON and works with the built-in Grape JSON formatter. Add `Roar::Representer::JSON`
+into your models or call `to_json` explicitly in your API implementation.
+
+### Rabl
 
-Entities with duplicate exposure names and conditions will silently overwrite one another.
-In the following example, when `object.check` equals "foo", only `field_a` will be exposed.
-However, when `object.check` equals "bar" both `field_b` and `foo` will be exposed.
+You can use [Rabl](https://github.com/nesquena/rabl) templates with the help of the
+[grape-rabl](https://github.com/LTe/grape-rabl) gem, which defines a custom Grape Rabl
+formatter.
+
+## Authentication
+
+### Basic and Digest Auth
+
+Grape has built-in Basic and Digest authentication.
 
 ```ruby
-module API
-  module Entities
-    class Status < Grape::Entity
-      expose :field_a, :foo, :if => lambda { |object, options| object.check == "foo" }
-      expose :field_b, :foo, :if => lambda { |object, options| object.check == "bar" }
-    end
-  end
+http_basic do |username, password|
+  # verify user's password here
+  { 'test' => 'password1' }[username] == password
 end
 ```
 
-This can be problematic, when you have mixed collections. Using `respond_to?` is safer.
-
 ```ruby
-module API
-  module Entities
-    class Status < Grape::Entity
-      expose :field_a, :if => lambda { |object, options| object.check == "foo" }
-      expose :field_b, :if => lambda { |object, options| object.check == "bar" }
-      expose :foo, :if => lambda { |object, options| object.respond_to?(:foo) }
-    end
-  end
+http_digest({ :realm => 'Test Api', :opaque => 'app secret' }) do |username|
+  # lookup the user's password here
+  { 'user1' => 'password1' }[username]
 end
 ```
 
-## Hypermedia and other RESTful Representations
-
-Although Grape ships with its own entity support, it's also possible to use it with other frameworks and renderers.
-
-### Hypermedia
-
-Use [Roar](https://github.com/apotonick/roar). Include `Roar::Representer::JSON` in your models or call `to_json` explicitly on representers in your API.
-
-### Rabl
-
-[Rabl](https://github.com/nesquena/rabl) is supported via the [grape-rabl](https://github.com/LTe/grape-rabl) gem.
+Use [warden-oauth2](https://github.com/opperator/warden-oauth2) or [rack-oauth2](https://github.com/nov/rack-oauth2) for OAuth2 support.
 
 ## Describing and Inspecting an API
 
@@ -981,6 +994,16 @@ class ApiLogger < Grape::Middleware::Base
 end
 ```
 
+## Before and After
+
+Execute a block before or after every API call with `before` and `after`.
+
+```ruby
+before do
+  header "X-Robots-Tag", "noindex"
+end
+```
+
 ## Anchoring
 
 Grape by default anchors all request paths, which means that the request URL
@@ -1080,6 +1103,36 @@ RSpec.configure do |config|
   }
 end
 ```
+
+## Reloading API Changes in Development
+
+### Rails 3.x
+
+Add API paths to `config/application.rb`.
+
+```ruby
+# Auto-load API and its subdirectories
+config.paths.add "app/api", :glob => "**/*.rb"
+config.autoload_paths += Dir["#{Rails.root}/app/api/*"]
+```
+
+Create `config/initializers/reload_api.rb`.
+
+```ruby
+if Rails.env.development?
+  api_files = Dir["#{Rails.root}/app/api/**/*.rb"]
+  api_reloader = ActiveSupport::FileUpdateChecker.new(api_files) do
+    Rails.application.reload_routes!
+  end
+  ActionDispatch::Callbacks.to_prepare do
+    api_reloader.execute_if_updated
+  end
+end
+```
+
+See [StackOverflow #3282655](http://stackoverflow.com/questions/3282655/ruby-on-rails-3-reload-lib-directory-for-each-request/4368838#4368838) for more information.
+
+
 ## Performance Monitoring
 
 Grape integrates with NewRelic via the [newrelic-grape](https://github.com/flyerhzm/newrelic-grape) gem.