grape 0.2.0 → 0.2.1

data/CHANGELOG.markdown

@@ -0,0 +1,68 @@
+0.2.1 (7/11/2012)
+=================
+
+* [#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).
+* [#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).
+* [#166](https://github.com/intridea/grape/pull/166): Added support for `redirect`, including permanent and temporary - [@allenwei](https://github.com/allenwei).
+* [#159](https://github.com/intridea/grape/pull/159): Added `:requirements` to routes, allowing to use reserved characters in paths - [@gaiottino](https://github.com/gaiottino).
+* [#156](https://github.com/intridea/grape/pull/156): Added support for adding formatters to entities - [@bobbytables](https://github.com/bobbytables).
+* [#183](https://github.com/intridea/grape/pull/183): Added ability to include documentation in entities - [@flah00](https://github.com/flah00).
+* [#189](https://github.com/intridea/grape/pull/189): `HEAD` requests no longer return a body - [@stephencelis](https://github.com/stephencelis).
+* [#97](https://github.com/intridea/grape/issues/97): Allow overriding `Content-Type` - [@dblock](https://github.com/dblock).
+
+0.2.0 (3/28/2012)
+=================
+
+* Added support for inheriting exposures from entities - [@bobbytables](https://github.com/bobbytables).
+* Extended formatting with `default_format` - [@dblock](https://github.com/dblock).
+* Added support for cookies - [@lukaszsliwa](https://github.com/lukaszsliwa).
+* Added support for declaring additional content-types - [@joeyAghion](https://github.com/joeyAghion).
+* Added support for HTTP PATCH - [@LTe](https://github.com/LTe).
+* Added support for describing, documenting and reflecting APIs - [@dblock](https://github.com/dblock).
+* Added support for anchoring and vendoring - [@jwkoelewijn](https://github.com/jwkoelewijn).
+* Added support for HTTP OPTIONS - [@grimen](https://github.com/grimen).
+* Added support for silencing logger - [@evansj](https://github.com/evansj).
+* Added support for helper modules - [@freelancing-god](https://github.com/freelancing-god).
+* Added support for Accept header-based versioning - [@jch](https://github.com/jch), [@rodzyn](https://github.com/rodzyn).
+* Added support for mounting APIs and other Rack applications within APIs - [@mbleigh](https://github.com/mbleigh).
+* Added entities, multiple object representations - [@mbleigh](https://github.com/mbleigh).
+* Added ability to handle XML in the incoming request body - [@jwillis](https://github.com/jwillis).
+* Added support for a configurable logger - [@mbleigh](https://github.com/mbleigh).
+* Added support for before and after filters - [@mbleigh](https://github.com/mbleigh).
+* Extended `rescue_from`, which can now take a block - [@dblock](https://github.com/dblock).
+
+
+0.1.5 (6/14/2011)
+==================
+
+* Extended exception handling to all exceptions - [@dblock](https://github.com/dblock).
+* Added support for returning JSON objects from within error blocks - [@dblock](https://github.com/dblock).
+* Added support for handling incoming JSON in body - [@tedkulp](https://github.com/tedkulp).
+* Added support for HTTP digest authentication - [@daddz](https://github.com/daddz).
+
+0.1.4 (4/8/2011)
+==================
+
+* Allow multiple definitions of the same endpoint under multiple versions - [@chrisrhoden](https://github.com/chrisrhoden).
+* Added support for multipart URL parameters - [@mcastilho](https://github.com/mcastilho).
+* Added support for custom formatters - [@spraints](https://github.com/spraints).
+
+0.1.3 (1/10/2011)
+==================
+
+* Added support for JSON format in route matching - [@aiwilliams](https://github.com/aiwilliams).
+* Added suport for custom middleware - [@mbleigh](https://github.com/mbleigh).
+
+0.1.1 (11/14/2010)
+==================
+
+* Endpoints properly reset between each request - [@mbleigh](https://github.com/mbleigh).
+
+0.1.0 (11/13/2010)
+==================
+
+* Initial public release - [@mbleigh](https://github.com/mbleigh).

data/README.markdown

@@ -77,9 +77,18 @@ class Twitter::API < Grape::API
 end
 ```
 
+Optionally, you can define requirements for your named route parameters using regular expressions. The route will match only if
+all requirements are met.
+
+```ruby
+get '/show/:id', :requirements => { :id => /[0-9]*/ } do
+  Tweet.find(params[:id])
+end
+```
+
 ## Mounting
 
-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
@@ -110,12 +119,16 @@ end
 
 ## Versioning
 
-There are two stragies in which clients can reach your API's endpoints: `:header` 
-and `:path`. The default strategy is `:header`.
+There are three strategies in which clients can reach your API's endpoints: `:header`, `:path` and `:param`. The default strategy is `:header`.
+
 
-    version 'v1', :using => :header
+### Header
+
+```ruby
+version 'v1', :using => :header
+```
 
-Using this versioning strategy, clients should pass the desired version in the HTTP Accept head. 
+Using this versioning strategy, clients should pass the desired version in the HTTP Accept head.
 
     curl -H Accept=application/vnd.twitter-v1+json http://localhost:9292/statuses/public_timeline
 
@@ -124,23 +137,59 @@ 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 `404 Not found` error
 is returned when no correct Accept header is supplied.
 
-    version 'v1', :using => :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
 
-Serialization takes place automatically. 
+Serialization takes place automatically.
+
+### Param
+
+```ruby
+version 'v1', :using => :param
+```
+
+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
+
+The default name for the query parameter is 'apiver' but can be specified using the :parameter option.
+
+```ruby
+version 'v1', :using => :param, :parameter => "v"
+```
+
+    curl -H http://localhost:9292/events?v=v1
 
 ## Parameters
 
-Parameters are available through the `params` hash object. This includes `GET` and `POST` parameters, 
+Parameters are available through the `params` hash object. This includes `GET` and `POST` parameters,
 along with any named parameters you specify in your route strings.
 
 ```ruby
-  get do
+get do
     Article.order(params[:sort_by])
-  end
+end
+```
+
+Parameters are also populated from the request body on POST and PUT for JSON and XML content-types.
+
+The Request:
+
+```curl -d '{"some_key": "some_value"}' 'http://localhost:9292/json_endpoint' -H Content-Type:application/json -v```
+
+The Grape Endpoint:
+
+```ruby
+post '/json_endpoint' do
+    params[:some_key]
+end
 ```
 
 ## Headers
@@ -148,10 +197,10 @@ along with any named parameters you specify in your route strings.
 Headers are available through the `env` hash object.
 
 ```ruby
-  get do
+get do
     error! 'Unauthorized', 401 unless env['HTTP_SECRET_PASSWORD'] == 'swordfish'
     ...
-  end
+end
 ```
 
 ## Helpers
@@ -213,6 +262,19 @@ cookies[:counter] = {
 }
 cookies[:counter][:value] +=1
 ```
+## Redirect
+
+You can redirect to a new url
+
+``` ruby
+redirect "/new_url"
+```
+
+use permanent redirect
+
+``` ruby
+redirect "/new_url", :permanent => true
+```
 
 ## Raising Errors
 
@@ -292,6 +354,51 @@ class Twitter::API < Grape::API
 end
 ```
 
+## Logging
+
+`Grape::API` provides a `logger` method which by default will return an instance of the `Logger`
+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
+class API < Grape::API
+  helpers do
+    def logger
+      API.logger
+    end
+  end
+  get '/hello' do
+    logger.info "someone said hello"
+    "hey there"
+  end
+end
+```
+
+You can also set your own logger:
+
+``` ruby
+class MyLogger
+  def warning(message)
+    puts "this is a warning: #{message}"
+  end
+end
+
+class API < Grape::API
+  logger MyLogger.new
+  helpers do
+    def logger
+      API.logger
+    end
+  end
+  get '/hello' do
+    logger.warning "someone said hello"
+    "hey there"
+  end
+end
+```
+
 ## Content-Types
 
 By default, Grape supports _XML_, _JSON_, _Atom_, _RSS_, and _text_ content-types.
@@ -319,9 +426,20 @@ class Twitter::API < Grape::API
 end
 ```
 
+You can override the content-type by setting the `Content-Type` header.
+
+``` ruby
+class API < Grape::API
+  get '/script' do
+    content_type "application/javascript"
+    "var x = 1;"
+  end
+end
+```
+
 ## Writing Tests
 
-You can test a Grape API with RSpec by making HTTP requests and examining the response. 
+You can test a Grape API with RSpec by making HTTP requests and examining the response.
 
 ### Writing Tests with Rack
 
@@ -349,7 +467,7 @@ describe Twitter::API do
       it "returns a status by id" do
         status = Status.create!
         get "/api/v1/statuses/#{status.id}"
-        last_resonse.body.should == status.to_json
+        last_response.body.should == status.to_json
       end
     end
   end
@@ -390,11 +508,122 @@ RSpec.configure do |config|
 end
 ```
 
+## Reusable Responses with Entities
+
+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.
+
+### Defining 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.
+
+  * `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
+
+``` 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
+    end
+  end
+end
+
+module API
+  module Entities
+    class UserDetailed < API::Entities::User
+      expose :account_id
+    end
+  end
+end
+```
+
+### 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 Users < Grape::API
+    version 'v1'
+
+    desc 'User index', {
+      :object_fields => API::Entities::User.documentation
+    }
+    get '/users' do
+      @users = User.all
+      type = current_user.admin? ? :full : :default
+      present @users, with: API::Entities::User, :type => type
+    end
+  end
+end
+```
+
+### Caveats
+
+Entities with duplicate exposure names and conditions will silently overwrite one another.
+In the following example, when object#check equals "foo", only afield will be exposed.
+However, when object#check equals "bar" both bfield and foo will be exposed.
+
+```ruby
+module API
+  module Entities
+    class User < Grape::Entity
+      expose :afield, :foo, :if => lambda{|object,options| object.check=="foo"}
+      expose :bfield, :foo, :if => lambda{|object,options| object.check=="bar"}
+    end
+  end
+end
+```
+
+This can be problematic, when you have mixed collections. Using #respond_to? is safer.
+
+```ruby
+module API
+  module Entities
+    class User < Grape::Entity
+      expose :afield, :if => lambda{|object,options| object.check=="foo"}
+      expose :bfield, :if => lambda{|object,options| object.check=="bar"}
+      expose :foo, :if => lambda{object,options| object.respond_to?(:foo)}
+    end
+  end
+end
+```
+
 ## Describing and Inspecting an API
 
 Grape lets you add a description to an API along with any other optional
 elements that can also be inspected at runtime.
-This can be useful for generating documentation.
+This can be useful for generating documentation. If the response
+requires documentation, consider using an entity.
 
 ``` ruby
 class TwitterAPI < Grape::API
@@ -432,13 +661,13 @@ Parameters can also be tagged to the method declaration itself.
 
 ``` ruby
 class StringAPI < Grape::API
-  get "split/:string", { :params => [ "token" ], :optional_params => [ "limit" ] } do
+  get "split/:string", { :params => { "token" => "a token" }, :optional_params => { "limit" => "the limit" } } do
     params[:string].split(params[:token], (params[:limit] || 0))
   end
 end
 
-StringAPI::routes[0].route_params # yields an array [ "string", "token" ]
-StringAPI::routes[0].route_optional_params # yields an array [ "limit" ]
+StringAPI::routes[0].route_params # yields a hash {"string" => "", "token" => "a token"}
+StringAPI::routes[0].route_optional_params # yields a hash {"limit" => "the limit"}
 ```
 
 It's possible to retrieve the information about the current route from within an API call with `route`.
@@ -452,6 +681,33 @@ class MyAPI < Grape::API
 end
 ```
 
+You can use this information to create a helper that will check if the request has
+all required parameters:
+
+``` ruby
+class MyAPI < Grape::API
+
+  helpers do
+    def validate_request!
+      # skip validation if no parameter is declared
+      return unless route.route_params
+      route.route_params.each do |k, v|
+        if !params.has_key? k
+          error!("Missing field: #{k}", 400)
+        end
+      end
+    end
+  end
+
+  before { validate_request! }
+
+  desc "creates a new item resource", :params => { :name => 'name is a required parameter' }
+  post :items do
+    ...
+  end
+end
+```
+
 ## Anchoring
 
 Grape by default anchors all request paths, which means that the request URL