Merge branch 'frontier' of github.com:intridea/grape into frontier

Author: Michael Bleigh

.gitignore

@@ -27,4 +27,7 @@ pkg
 dist
 Gemfile.lock
 
+## Rubinius
+.rbx
+
 ## PROJECT::SPECIFIC

Gemfile

@@ -9,4 +9,5 @@ group :development, :test do
   gem 'guard-bundler'
   gem 'rb-fsevent'
   gem 'growl'
+  gem 'json'
 end

README.markdown

@@ -1,8 +1,19 @@
-# Grape (Frontier) [![Build Status](http://travis-ci.org/intridea/grape.png)](http://travis-ci.org/intridea/grape)
+# Grape (Frontier) [![Build Status](http://travis-ci.org/intridea/grape.png?branch=frontier)](http://travis-ci.org/intridea/grape)
 
 **Welcome to the `frontier` branch. This is where we're experimenting and building the next version of Grape. Things will be civilized here one day, but until then you best carry your revolver with you.**
 
-Grape is a REST-like API micro-framework for Ruby. It is built to complement existing web application frameworks such as Rails and Sinatra by providing a simple DSL to easily provide APIs. It has built-in support for common conventions such as multiple formats, subdomain/prefix restriction, and versioning.
+## What is Grape?
+
+Grape is a REST-like API micro-framework for Ruby. It is built to complement
+existing web application frameworks such as Rails and Sinatra by providing a
+simple DSL to easily provide APIs. It has built-in support for common
+conventions such as multiple formats, subdomain/prefix restriction, and
+versioning.
+
+## Project Tracking
+
+* [Grape Google Group](http://groups.google.com/group/ruby-grape)
+* [Grape Wiki](https://github.com/intridea/grape/wiki)
 
 ## Installation
 
@@ -12,7 +23,9 @@ Grape is available as a gem, to install it just install the gem:
 
 ## Basic Usage
 
-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.
+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
@@ -61,7 +74,8 @@ class Twitter::API < Grape::API
 end
 ```
 
-This would create a Rack application that could be used like so (in a Rackup config.ru file):
+This would create a Rack application that could be used like so (in a Rackup
+config.ru file):
 
 ```ruby
 run Twitter::API
@@ -82,10 +96,14 @@ request:
 
     curl -H Accept=application/vnd.twitter-v1+json http://localhost:9292/statuses/public_timeline
 
-By default, the first matching version is used when no Accept header is supplied. This behavior is similar to routing in Rails.
-To circumvent this default behaviour, 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.
+By default, the first matching version is used when no Accept header is
+supplied. This behavior is similar to routing in Rails.
+To circumvent this default behaviour, 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.
 
-Serialization takes place automatically. For more detailed usage information, please visit the [Grape Wiki](http://github.com/intridea/grape/wiki).
+Serialization takes place automatically. For more detailed usage information,
+please visit the [Grape Wiki](http://github.com/intridea/grape/wiki).
 
 ## Helpers
 
@@ -117,39 +135,6 @@ class API < Grape::API
 end
 ````
 
-
-## Working with Entities
-
-A common problem in designing Ruby APIs is that you probably don't want
-the exact structure of your data models exposed. ActiveRecord, for
-instance, will dump all of its attributes. While you can override
-`#as_json` to alter this behavior somewhat, what is really needed is an
-intermediary layer between the model and the API. This is where the
-`Grape::Entity` class comes in.
-
-```ruby
-module Entities
-  class User < Grape::Entity
-    expose :first_name, :last_name
-    expose :email, :if => {:authenticated => true}
-    expose :name, :id => {:version => 'v1'} # deprecated
-  end
-end
-
-class API < Grape::API
-  version 'v1', 'v2'
-
-  get '/users/:id' do
-    present User.find(params[:id]),
-      :with => Entities::User,
-      :authenticated => env.key?('api.token')
-  end
-end
-```
-
-For more information about Entities, view the project's YARD
-documentation.
-
 ## Raising Errors
 
 You can raise errors explicitly.
@@ -158,7 +143,8 @@ You can raise errors explicitly.
 error!("Access Denied", 401)
 ```
 
-You can also return JSON formatted objects explicitly by raising error! and passing a hash instead of a message.
+You can also return JSON formatted objects explicitly by raising error! and
+passing a hash instead of a message.
 
 ```ruby
 error!({ "error" => "unexpected error", "detail" => "missing widget" }, 500)
@@ -183,15 +169,17 @@ 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 can be specified using `error_format`. Available formats are
+`:json` and `:txt` (default).
 
 ```ruby
 class Twitter::API < Grape::API
   error_format :json
 end
 ```
 
-You can rescue all exceptions with a code block. The `rack_response` wrapper automatically sets the default error code and content-type.
+You can rescue all exceptions with a code block. The `rack_response` wrapper
+automatically sets the default error code and content-type.
 
 ```ruby
 class Twitter::API < Grape::API
@@ -201,7 +189,8 @@ class Twitter::API < Grape::API
 end
 ```
 
-You can also rescue specific exceptions with a code block and handle the Rack response at the lowest level.
+You can also rescue specific exceptions with a code block and handle the Rack
+response at the lowest level.
 
 ```ruby
 class Twitter::API < Grape::API
@@ -220,9 +209,22 @@ end
       end
     end
 
+## Content-Types
+
+By default, Grape supports _XML_, _JSON_, _Atom_, _RSS_, and _text_ content-types. Your API can declare additional types to support. Response format is determined by the request's extension or `Accept` header.
+
+```ruby
+class Twitter::API < Grape::API
+  content_type :xls, "application/vnd.ms-excel"
+end
+```
+
 ## Writing Tests
 
-You can test a Grape API with RSpec. Tests make HTTP requests, therefore they must go into the `spec/request` group. You may want your API code to go into `app/api` - you can match that layout under `spec` by adding the following in `spec/spec_helper.rb`.
+You can test a Grape API with RSpec. Tests make HTTP requests, therefore they
+must go into the `spec/request` group. You may want your API code to go into
+`app/api` - you can match that layout under `spec` by adding the following in
+`spec/spec_helper.rb`.
 
 ```ruby
 RSpec.configure do |config|
@@ -250,7 +252,8 @@ 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. 
+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.
 
 ```ruby
@@ -272,7 +275,11 @@ class TwitterAPI < Grape::API
 end
 ```
 
-Grape then exposes arrays of API versions and compiled routes. Each route contains a `route_prefix`, `route_version`, `route_namespace`, `route_method`, `route_path` and `route_params`. The description and the optional hash that follows the API path may contain any number of keys and its values are also accessible via dynamically-generated `route_[name]` functions.
+Grape then exposes arrays of API versions and compiled routes. Each route
+contains a `route_prefix`, `route_version`, `route_namespace`, `route_method`,
+`route_path` and `route_params`. The description and the optional hash that
+follows the API path may contain any number of keys and its values are also
+accessible via dynamically-generated `route_[name]` functions.
 
 ```ruby
 TwitterAPI::versions # yields [ 'v1', 'v2' ]
@@ -294,14 +301,50 @@ StringAPI::routes[0].route_params # yields an array [ "string", "token" ]
 StringAPI::routes[0].route_optional_params # yields an array [ "limit" ]
 ```
 
+## Anchoring
+
+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 known up
+front 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.
+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
+    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.
+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 everyting that comes after the '/urls/'
+part.
+
 ## Note on Patches/Pull Requests
 
-* Fork the project.
-* Make your feature addition or bug fix.
-* Add tests for it. This is important so I don't break it in a future version unintentionally.
-* Commit, do not mess with Rakefile, version, or history. (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
-* Send me a pull request. Bonus points for topic branches.
+* 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
+* Commit, push and make a pull request. Bonus points for topical branches.
+
+## License
+
+MIT License. See LICENSE for details.
 
 ## Copyright
 
-Copyright (c) 2010 Michael Bleigh and Intridea, Inc. See LICENSE for details.
+Copyright (c) 2010-2012 Michael Bleigh and Intridea, Inc. 
+

grape.gemspec

@@ -10,6 +10,7 @@ Gem::Specification.new do |s|
   s.homepage    = "https://github.com/intridea/grape"
   s.summary     = %q{A simple Ruby framework for building REST-like APIs.}
   s.description = %q{A Ruby framework for rapid API development with great conventions.}
+  s.license     = "MIT"
 
   s.rubyforge_project = "grape"
 

lib/grape/api.rb

@@ -48,7 +48,6 @@ def call(env)
       end
 
       def call!(env)
-        logger.info "#{env['REQUEST_METHOD']} #{env['PATH_INFO']}"
         instance.call(env)
       end
 
@@ -96,7 +95,7 @@ def version(*args, &block)
         if args.any?
           options = args.pop if args.last.is_a? Hash
           options ||= {}
-          options = {:using => :header}.merge!(options)
+          options = {:using => :path}.merge!(options)
           @versions = versions | args
           nest(block) do
             set(:version, args)
@@ -123,6 +122,12 @@ def error_format(new_format = nil)
         new_format ? set(:error_format, new_format.to_sym) : settings[:error_format]
       end
 
+      # Specify additional content-types, e.g.:
+      #   content_type :xls, 'application/vnd.ms-excel'
+      def content_type(key, val)
+        settings.imbue(:content_types, key.to_sym => val)
+      end
+
       # Specify the default status code for errors.
       def default_error_status(new_status = nil)
         new_status ? set(:default_error_status, new_status) : settings[:default_error_status]
@@ -279,7 +284,7 @@ def before(&block)
         imbue(:befores, [block])
       end
 
-      def after(&block) 
+      def after(&block)
         imbue(:afters, [block])
       end
 
@@ -288,6 +293,7 @@ def post(paths = ['/'], options = {}, &block); route('POST', paths, options, &bl
       def put(paths = ['/'], options = {}, &block); route('PUT', paths, options, &block) end
       def head(paths = ['/'], options = {}, &block); route('HEAD', paths, options, &block) end
       def delete(paths = ['/'], options = {}, &block); route('DELETE', paths, options, &block) end
+      def options(paths = ['/'], options = {}, &block); route('OPTIONS', paths, options, &block) end
 
       def namespace(space = nil, &block)
         if space || block_given?
@@ -334,11 +340,11 @@ def middleware
       def routes
         @routes ||= prepare_routes
       end
-      
+
       def versions
         @versions ||= []
       end
-      
+
       protected
 
       def prepare_routes