grape 0.2.2 → 0.2.3

data/CHANGELOG.markdown

@@ -1,5 +1,19 @@
-0.2.2 (Next Release)
-====================
+0.2.3 (24/12/2012)
+==================
+
+* [#179](https://github.com/intridea/grape/issues/178): Using `content_type` will remove all default content-types - [@dblock](https://github.com/dblock).
+* [#265](https://github.com/intridea/grape/issues/264): Fix: Moved `ValidationError` into `Grape::Exceptions` - [@thepumpkin1979](https://github.com/thepumpkin1979).
+* [#269](https://github.com/intridea/grape/pull/269): Fix: `LocalJumpError` will not be raised when using explict return in API methods - [@simulacre](https://github.com/simulacre).
+* [#86](https://github.com/intridea/grape/issues/275): Fix Path-based versioning not recognizing `/` route - [@walski](https://github.com/walski).
+* [#273](https://github.com/intridea/grape/pull/273): Disabled formatting via `serializable_hash` and added support for `format :serializable_hash` - [@dblock](https://github.com/dblock).
+* [#277](https://github.com/intridea/grape/pull/277): Added a DSL to declare `formatter` in API settings - [@tim-vandecasteele](https://github.com/tim-vandecasteele).
+* [#284](https://github.com/intridea/grape/pull/284): Added a DSL to declare `error_formatter` in API settings - [@dblock](https://github.com/dblock).
+* [#285](https://github.com/intridea/grape/pull/285): Removed `error_format` from API settings, now matches request format - [@dblock](https://github.com/dblock).
+* [#290](https://github.com/intridea/grape/pull/290): The default error format for XML is now `error/message` instead of `hash/error` - [@dpsk](https://github.com/dpsk).
+* [#44](https://github.com/intridea/grape/issues/44): Pass `env` into formatters to enable templating - [@dblock](https://github.com/dblock).
+
+0.2.2
+=====
 
 Features
 --------
@@ -21,7 +35,7 @@ Fixes
 * [#181](https://github.com/intridea/grape/pull/181): Fix: Corrected JSON serialization of nested hashes containing `Grape::Entity` instances - [@benrosenblum](https://github.com/benrosenblum).
 * [#203](https://github.com/intridea/grape/pull/203): Added a check to `Entity#serializable_hash` that verifies an entity exists on an object - [@adamgotterer](https://github.com/adamgotterer).
 * [#208](https://github.com/intridea/grape/pull/208): `Entity#serializable_hash` must also check if attribute is generated by a user supplied block - [@ppadron](https://github.com/ppadron).
-* [#252](https://github.com/intridea/grape/pull/252): Resources that don't respond to a requested HTTP method return 405 (Method Not Allowed) instead of 404 (Not Found) [@simulacre](https://github.com/simulacre)
+* [#252](https://github.com/intridea/grape/pull/252): Resources that don't respond to a requested HTTP method return 405 (Method Not Allowed) instead of 404 (Not Found) - [@simulacre](https://github.com/simulacre)
 
 0.2.1 (7/11/2012)
 =================

data/Gemfile

@@ -10,6 +10,6 @@ group :development, :test do
   gem 'rb-fsevent'
   gem 'growl'
   gem 'json'
-  gem 'rspec' 
+  gem 'rspec'
   gem 'rack-test', "~> 0.6.2", :require => "rack/test"
 end

data/README.markdown

@@ -3,9 +3,9 @@
 ## What is Grape?
 
 Grape is a REST-like API micro-framework for Ruby. It's designed to run on Rack
-or complement existing web application frameworks such as Rails and Sinatra by 
-providing a simple DSL to easily develop RESTful APIs. It has built-in support 
-for common conventions, including multiple formats, subdomain/prefix restriction, 
+or complement existing web application frameworks such as Rails and Sinatra by
+providing a simple DSL to easily develop RESTful APIs. It has built-in support
+for common conventions, including multiple formats, subdomain/prefix restriction,
 content negotiation, versioning and much more.
 
 [![Build Status](https://travis-ci.org/intridea/grape.png?branch=master)](http://travis-ci.org/intridea/grape)
@@ -15,6 +15,11 @@ 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:
@@ -49,37 +54,60 @@ class Twitter::API < Grape::API
   end
 
   resource :statuses do
-  
-    desc "Returns a public timeline."
+
+    desc "Return a public timeline."
     get :public_timeline do
-      Tweet.limit(20)
+      Status.limit(20)
     end
 
-    desc "Returns a personal timeline."
+    desc "Return a personal timeline."
     get :home_timeline do
       authenticate!
-      current_user.home_timeline
+      current_user.statuses.limit(20)
     end
 
-    desc "Returns a tweet."
+    desc "Return a status."
     params do
-      requires :id, :type => Integer, :desc => "Tweet id."
+      requires :id, :type => Integer, :desc => "Status id."
     end
-    get '/show/:id' do
-      Tweet.find(params[:id])
+    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 "Creates a tweet."
+
+    desc "Update a status."
     params do
+      requires :id, :type => String, :desc => "Status ID."
       requires :status, :type => String, :desc => "Your status."
     end
-    post :update do
+    put ':id' do
       authenticate!
-      Tweet.create(
+      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
+
   end
 
 end
@@ -98,10 +126,12 @@ run Twitter::API
 
 And would respond to the following routes:
 
-    GET  /statuses/public_timeline(.json)
-    GET  /statuses/home_timeline(.json)
-    GET  /statuses/show/:id(.json)
-    POST /statuses/update(.json)
+    GET /statuses/public_timeline(.json)
+    GET /statuses/home_timeline(.json)
+    GET /statuses/:id(.json)
+    POST /statuses(.json)
+    PUT /statuses/:id(.json)
+    DELETE /statuses/:id(.json)
 
 ### Rails
 
@@ -111,7 +141,7 @@ In a Rails application, modify *config/routes*:
 mount Twitter::API => "/"
 ```
 
-Note that you will need to restart Rails to pick up changes in your API classes
+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)).
 
 ### Modules
@@ -128,7 +158,7 @@ end
 
 ## Versioning
 
-There are three strategies in which clients can reach your API's endpoints: `:header`, 
+There are three strategies in which clients can reach your API's endpoints: `:header`,
 `:path` and `:param`. The default strategy is `:path`.
 
 ### Header
@@ -162,10 +192,10 @@ Using this versioning strategy, clients should pass the desired version in the U
 version 'v1', :using => :param
 ```
 
-Using this versioning strategy, clients should pass the desired version as a request parameter, 
+Using this versioning strategy, clients should pass the desired version as a request parameter,
 either in the URL query string or in the request body.
 
-    curl -H http://localhost:9292/events?apiver=v1
+    curl -H http://localhost:9292/statuses/public_timeline?apiver=v1
 
 The default name for the query parameter is 'apiver' but can be specified using the `:parameter` option.
 
@@ -173,16 +203,16 @@ The default name for the query parameter is 'apiver' but can be specified using
 version 'v1', :using => :param, :parameter => "v"
 ```
 
-    curl -H http://localhost:9292/events?v=v1
+    curl -H http://localhost:9292/statuses/public_timeline?v=v1
 
 ## Describing Methods
 
 You can add a description to API methods and namespaces.
 
 ``` ruby
-desc "Returns a reticulated spline."
-get "spline/:id" do
-  Spline.find(params[:id])
+desc "Returns your public timeline."
+get :public_timeline do
+  Status.limit(20)
 end
 ```
 
@@ -192,8 +222,8 @@ Request parameters are available through the `params` hash object. This includes
 along with any named parameters you specify in your route strings.
 
 ```ruby
-get do
-  Article.order(params[:sort_by])
+get :public_timeline do
+  Status.order(params[:sort_by])
 end
 ```
 
@@ -201,13 +231,13 @@ Parameters are also populated from the request body on POST and PUT for JSON and
 
 The Request:
 
-```curl -d '{"some_key": "some_value"}' 'http://localhost:9292/json_endpoint' -H Content-Type:application/json -v```
+```curl -d '{"text": "140 characters"}' 'http://localhost:9292/statuses' -H Content-Type:application/json -v```
 
 The Grape Endpoint:
 
 ```ruby
-post '/json_endpoint' do
-    params[:some_key]
+post '/statuses' do
+  Status.create!({ :text => params[:text] })
 end
 ```
 
@@ -218,59 +248,58 @@ You can define validations and coercion options for your parameters using a `par
 ```ruby
 params do
   requires :id, type: Integer
-  optional :name, type: String, regexp: /^[a-z]+$/
-
-  group :user do
-    requires :first_name
-    requires :last_name
+  optional :text, type: String, regexp: /^[a-z]+$/
+  group :media do
+    requires :url
   end
 end
-get ':id' do
+put ':id' do
   # params[:id] is an Integer
 end
 ```
 
-When a type is specified an implicit validation is done after the coercion to ensure 
+When a type is specified an implicit validation is done after the coercion to ensure
 the output type is the one declared.
 
-Parameters can be nested using `group`. In the above example, this means both
-`params[:user][:first_name]` and `params[:user][:last_name]` are required next to `params[:id]`.
+Parameters can be nested using `group`. In the above example, this means
+`params[:media][:url]` is required along with `params[:id]`.
 
 ### Namespace Validation and Coercion
+
 Namespaces allow parameter definitions and apply to every method within the namespace.
 
 ```ruby
-namespace :shelves do
+namespace :statuses do
   params do
-    requires :shelf_id, type: Integer, desc: "A shelf."
+    requires :user_id, type: Integer, desc: "A user ID."
   end
-  namespace ":shelf_id" do
-    desc "Retrieve a book from a shelf."
+  namespace ":user_id" do
+    desc "Retrieve a user's status."
     params do
-      requires :book_id, type: Integer, desc: "A book."
+      requires :status_id, type: Integer, desc: "A status ID."
     end
-    get ":book_id" do
-      # params[:shelf_id] defines a shelf
-      # params[:book_id] defines a book
+    get ":status_id" do
+      User.find(params[:user_id]).statuses.find(params[:status_id])
     end
   end
 end
 ```
 
 ### Custom Validators
+
 ```ruby
 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"
-    end    
+    end
   end
-end  
+end
 ```
 
 ```ruby
 params do
-  requires :username, :alpha_numeric => true
+  requires :text, :alpha_numeric => true
 end
 ```
 
@@ -279,33 +308,33 @@ You can also create custom classes that take parameters.
 ```ruby
 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 #{@option} characters long"
-    end    
+    unless params[attr_name].length <= @option
+      throw :error, :status => 400, :message => "#{attr_name}: must be at the most #{@option} characters long"
+    end
   end
-end  
-``` 
+end
+```
 
 ```ruby
 params do
-  requires :name, :length => 5
+  requires :text, :length => 140
 end
 ```
 
 ### Validation Errors
 
-When validation and coercion erros occur an exception of type `ValidationError` is raised.
+When validation and coercion errors occur an exception of type `Grape::Exceptions::ValidationError` is raised.
 If the exception goes uncaught it will respond with a status of 400 and an error message.
-You can rescue a `ValidationError` and respond with a custom response.
+You can rescue a `Grape::Exceptions::ValidationError` and respond with a custom response.
 
 ```ruby
-rescue_from ValidationError do |e|
+rescue_from Grape::Exceptions::ValidationError do |e|
     Rack::Response.new({
         'status' => e.status,
         'message' => e.message,
         'param' => e.param
-    }.to_json, e.status)    
-end 
+    }.to_json, e.status)
+end
 ```
 
 ## Headers
@@ -321,7 +350,7 @@ end
 
 ```ruby
 get do
-    error! 'Unauthorized', 401 unless env['HTTP_SECRET_PASSWORD'] == 'swordfish'
+    error!('Unauthorized', 401) unless env['HTTP_SECRET_PASSWORD'] == 'swordfish'
     ...
 end
 ```
@@ -332,8 +361,8 @@ Optionally, you can define requirements for your named route parameters using re
 expressions. The route will match only if all requirements are met.
 
 ```ruby
-get '/show/:id', :requirements => { :id => /[0-9]*/ } do
-  Tweet.find(params[:id])
+get ':id', :requirements => { :id => /[0-9]*/ } do
+  Status.find(params[:id])
 end
 ```
 
@@ -343,9 +372,9 @@ You can define helper methods that your endpoints can use with the `helpers`
 macro by either giving a block or a module.
 
 ``` ruby
-module MyHelpers
-  def say_hello(user)
-    "hey there #{user.name}"
+module StatusHelpers
+  def user_info(user)
+    "#{user} has statused #{user.statuses} status(s)"
   end
 end
 
@@ -358,11 +387,11 @@ class API < Grape::API
   end
 
   # or mix in a module
-  helpers MyHelpers
+  helpers StatusHelpers
 
-  get '/hello' do
+  get 'info' do
     # helpers available in your endpoint and filters
-    say_hello(current_user)
+    user_info(current_user)
   end
 end
 ```
@@ -373,28 +402,31 @@ You can set, get and delete your cookies very simply using `cookies` method.
 
 ``` ruby
 class API < Grape::API
-  get '/counter' do
-    cookies[:counter] ||= 0
-    cookies[:counter] += 1
-    { :counter => cookies[:counter] }
+
+  get 'status_count' do
+    cookies[:status_count] ||= 0
+    cookies[:status_count] += 1
+    { :status_count => cookies[:status_count] }
   end
 
-  delete '/counter' do
-    { :result => cookies.delete(:counter) }
+  delete 'status_count' do
+    { :status_count => cookies.delete(:status_count) }
   end
+
 end
 ```
 
-To set more than value use hash-based syntax.
+Use a hash-based syntax to set more than one value.
 
 ``` ruby
-cookies[:counter] = {
+cookies[:status_count] = {
     :value => 0,
     :expires => Time.tomorrow,
-    :domain => '.example.com',
+    :domain => '.twitter.com',
     :path => '/'
 }
-cookies[:counter][:value] +=1
+
+cookies[:status_count][:value] +=1
 ```
 
 ## Redirecting
@@ -402,53 +434,54 @@ cookies[:counter][:value] +=1
 You can redirect to a new url temporarily (302) or permanently (301).
 
 ``` ruby
-redirect "/new_url"
+redirect "/statuses"
 ```
 
 ``` ruby
-redirect "/new_url", :permanent => true
+redirect "/statuses", :permanent => true
 ```
 
 ## Allowed Methods
 
 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.
+include an "Allow" header listing the supported methods.
 
 ``` ruby
 class API < Grape::API
-  get '/counter' do
-    { :counter => Counter.count }
+
+  get '/rt_count' do
+    { :rt_count => current_user.rt_count }
   end
 
   params do
-    requires :value, :type => Integer, :desc => 'value to add to counter'
+    requires :value, :type => Integer, :desc => 'Value to add to the rt count.'
   end
-  put '/counter' do
-    { :counter => Counter.incr(params.value) }
+  put '/rt_count' do
+    current_user.rt_count += params[:value].to_i
+    { :rt_count => current_user.rt_count }
   end
 end
 ```
 
 ``` shell
-curl -v -X OPTIONS http://localhost:3000/counter 
+curl -v -X OPTIONS http://localhost:3000/rt_count
 
-> OPTIONS /counter HTTP/1.1
-> 
+> OPTIONS /rt_count HTTP/1.1
+>
 < HTTP/1.1 204 No Content
 < Allow: OPTIONS, GET, PUT
 ```
 
-
 If a request for a resource is made with an unsupported HTTP method, an
 HTTP 405 (Method Not Allowed) response will be returned.
 
 ``` shell
-curl -X DELETE -v http://localhost:3000/counter/
+curl -X DELETE -v http://localhost:3000/rt_count/
 
-> DELETE /counter/ HTTP/1.1
+> DELETE /rt_count/ HTTP/1.1
 > Host: localhost:3000
-> 
+>
 < HTTP/1.1 405 Method Not Allowed
 < Allow: OPTIONS, GET, PUT
 ```
@@ -470,8 +503,7 @@ error!({ "error" => "unexpected error", "detail" => "missing widget" }, 500)
 
 ## Exception Handling
 
-Grape can be told to rescue all exceptions and instead return them in
-txt or json formats.
+Grape can be told to rescue all exceptions and return them in txt or json formats.
 
 ``` ruby
 class Twitter::API < Grape::API
@@ -487,12 +519,29 @@ class Twitter::API < Grape::API
 end
 ```
 
-The error format can be specified using `error_format`. Available formats are
-`:json` and `:txt` (default).
+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
 class Twitter::API < Grape::API
-  error_format :json
+  error_formatter :txt, lambda { |message, backtrace, options, env|
+    "error: #{message} from #{backtrace}"
+  }
+end
+```
+
+You can also use a module or class.
+
+``` ruby
+module CustomFormatter
+  def self.call(message, backtrace, options, env)
+    { message: message, backtrace: backtrace }
+  end
+end
+
+class Twitter::API < Grape::API
+  error_formatter :custom, CustomFormatter
 end
 ```
 
@@ -546,9 +595,9 @@ class API < Grape::API
       API.logger
     end
   end
-  get '/hello' do
-    logger.info "someone said hello"
-    "hey there"
+  post '/statuses' do
+    ...
+    logger.info "#{current_user} has statused"
   end
 end
 ```
@@ -569,9 +618,8 @@ class API < Grape::API
       API.logger
     end
   end
-  get '/hello' do
-    logger.warning "someone said hello"
-    "hey there"
+  get '/statuses' do
+    logger.warning "#{current_user} has statused"
   end
 end
 ```
@@ -581,23 +629,46 @@ end
 By default, Grape supports _XML_, _JSON_, _Atom_, _RSS_, and _text_ content-types.
 Serialization takes place automatically.
 
-Your API can declare additional types to support. Response format is determined by the
-request's extension, an explicit `format` parameter in the query string, or `Accept` header.
+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
+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
+class Twitter::API < Grape::API
+  format :json
+  content_type :json, "application/json"
+end
+```
+
+Custom formatters for existing and additional types can be defined with a proc.
 
 ``` ruby
 class Twitter::API < Grape::API
   content_type :xls, "application/vnd.ms-excel"
+  formatter :xls, lambda { |object, env| object.to_xls }
 end
 ```
 
-You can also set the default format. The order for choosing the format is the following.
+You can also use a module or class.
 
-* Use the file extension, if specified. If the file is .json, choose the JSON format.
-* Use the value of the `format` parameter in the query string, if specified.
-* 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.
+``` ruby
+module XlsFormatter
+  def self.call(object, env)
+    object.to_xls
+  end
+end
+
+class Twitter::API < Grape::API
+  content_type :xls, "application/vnd.ms-excel"
+  formatter :xls, XlsFormatter
+end
+```
+
+The default format is `:txt`. You can set the preferred format for an API that
+supports multiple formats with `format`.
 
 ``` ruby
 class Twitter::API < Grape::API
@@ -605,19 +676,39 @@ class Twitter::API < Grape::API
 end
 ```
 
+You can set the fallback, default format with `default_format`.
+
 ``` ruby
 class Twitter::API < Grape::API
   default_format :json
 end
 ```
 
-You can override the content-type by setting the `Content-Type` header.
+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.
+* Use the value of the `format` parameter in the query string, if specified.
+* 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.
+
+## Content-type
+
+You can override the content-type of the response by setting the `Content-Type` header.
 
 ``` ruby
 class API < Grape::API
-  get '/script' do
+  get '/home_timeline_js' do
     content_type "application/javascript"
-    "var x = 1;"
+    "var statuses = ...;"
   end
 end
 ```
@@ -656,21 +747,21 @@ array.
 ``` ruby
 module API
   module Entities
-    class User < Grape::Entity
-      expose :first_name, :last_name
-      expose :field, :documentation => { :type => "string", :desc => "words go here" }
-      expose :email, :if => { :type => :full }
-      expose :user_type, user_id, :if => lambda{ |user,options| user.confirmed? }
-      expose(:name) { |user,options| [ user.first_name, user.last_name ].join(' ')}
-      expose :latest_status, :using => API::Status, :as => :status
+    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 :replies, :using => API::Status, :as => :replies
     end
   end
 end
 
 module API
   module Entities
-    class UserDetailed < API::Entities::User
-      expose :account_id
+    class StatusDetailed < API::Entities::Status
+      expose :internal_id
     end
   end
 end
@@ -682,20 +773,18 @@ Grape ships with a DSL to easily define entities within the context
 of an existing class:
 
 ```ruby
-class User
+class Status
   include Grape::Entity::DSL
 
-  entity :name, :email do
-    expose :advanced, if: :conditional
+  entity :text, :user_id do
+    expose :detailed, if: :conditional
   end
 end
 ```
 
-The above will automatically create a `User::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.
+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
 
@@ -707,16 +796,16 @@ If the entity includes documentation it can be included in an endpoint's descrip
 
 ``` ruby
 module API
-  class Users < Grape::API
+  class Statuses < Grape::API
     version 'v1'
 
-    desc 'User index', {
-      :object_fields => API::Entities::User.documentation
+    desc 'Statuses index', {
+      :object_fields => API::Entities::Status.documentation
     }
-    get '/users' do
-      @users = User.all
+    get '/statues' do
+      statuses = Status.all
       type = current_user.admin? ? :full : :default
-      present @users, with: API::Entities::User, :type => type
+      present statues, with: API::Entities::Status, :type => type
     end
   end
 end
@@ -724,28 +813,25 @@ end
 
 ### Entity Organization
 
-In addition to separately organizing entities, it may be useful to
-put them as namespaced classes underneath the model they represent.
-For example:
+In addition to separately organizing entities, it may be useful to put them as namespaced
+classes underneath the model they represent.
 
 ```ruby
-class User
+class Status
   def entity
-    Entity.new(self)
+    Status.new(self)
   end
 
   class Entity < Grape::Entity
-    expose :name, :email
+    expose :text, :user_id
   end
 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 `User::Entity`
-class and use that as the representative entity. This can still
-be overridden by using the `:with` option or an explicit
+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
+representative entity. This can still be overridden by using the `:with` option or an explicit
 `represents` call.
 
 ### Caveats
@@ -757,7 +843,7 @@ However, when `object.check` equals "bar" both `field_b` and `foo` will be expos
 ```ruby
 module API
   module Entities
-    class User < Grape::Entity
+    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
@@ -770,7 +856,7 @@ This can be problematic, when you have mixed collections. Using `respond_to?` is
 ```ruby
 module API
   module Entities
-    class User < Grape::Entity
+    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) }
@@ -779,9 +865,21 @@ module API
 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.
+
 ## Describing and Inspecting an API
 
-Grape routes can be reflected at runtime. This can notably be useful for generating 
+Grape routes can be reflected at runtime. This can notably be useful for generating
 documentation.
 
 Grape exposes arrays of API versions and compiled routes. Each route
@@ -797,7 +895,7 @@ TwitterAPI::routes[0].route_version # yields 'v1'
 TwitterAPI::routes[0].route_description # etc.
 ```
 
-It's possible to retrieve the information about the current route from within an API 
+It's possible to retrieve the information about the current route from within an API
 call with `route`.
 
 ``` ruby
@@ -816,29 +914,29 @@ end
 
 Grape by default anchors all request paths, which means that the request URL
 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 
+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. 
+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.
 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
-class UrlAPI < Grape::API
-  namespace :urls do
-    get '/(*:url)', :anchor => false do
-      some_data
+class TwitterAPI < Grape::API
+  namespace :statues do
+    get '/(*:status)', :anchor => false do
+
     end
   end
 end
 ```
 
-This will match all paths starting with '/urls/'. There is one caveat though:
-the `params[:url]` parameter only holds the first part of the request url.
+This will match all paths starting with '/statuses/'. There is one caveat though:
+the `params[:status]` parameter only holds the first part of the request url.
 Luckily this can be circumvented by using the described above syntax for path
 specification and using the `PATH_INFO` Rack environment variable, using
-`env["PATH_INFO"]`. This will hold everything that comes after the '/urls/'
+`env["PATH_INFO"]`. This will hold everything that comes after the '/statuses/'
 part.
 
 ## Writing Tests
@@ -895,7 +993,7 @@ describe Twitter::API do
     it "returns a status by id" do
       status = Status.create!
       get "/api/v1/statuses/#{status.id}"
-      resonse.body.should == status.to_json
+      response.body.should == status.to_json
     end
   end
 end