Merge pull request ruby-grape#147 from dblock/frontier-default-format

Frontier: enable default_format to actually do something

Author: dblock

README.markdown

@@ -36,9 +36,9 @@ 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
+``` ruby
 class Twitter::API < Grape::API
-  version 'v1', :using => :header, :vendor => 'twitter', :format => :json
+  version 'v1', :using => :header, :vendor => 'twitter'
 
   helpers do
     def current_user
@@ -87,7 +87,7 @@ end
 
 The above sample creates a Rack application that can be run from a rackup *config.ru* file:
 
-```ruby
+``` ruby
 run Twitter::API
 ```
 And would respond to the following routes:
@@ -99,22 +99,22 @@ And would respond to the following routes:
 
 In a Rails application, modify *config/routes*:
 
-```ruby
+``` ruby
 mount Twitter::API => "/"
 ```
 
 ## Versioning
 
 Versioning is handled with HTTP Accept head by default, but can be configures
-to [use different strategies](https://github.com/intridea/grape/wiki/API-Versioning). 
+to [use different strategies](https://github.com/intridea/grape/wiki/API-Versioning).
 For example, to request the above with a version, you would make the following
 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 behavior, 
-one could use the `:strict` option. When this option is set to `true`, a `404 Not found` error 
+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 `404 Not found` error
 is returned when no correct Accept header is supplied.
 
 Serialization takes place automatically.
@@ -124,7 +124,7 @@ Serialization takes place automatically.
 You can define helper methods that your endpoints can use with the `helpers`
 macro by either giving a block or a module:
 
-````ruby
+``` ruby
 module MyHelpers
   def say_hello(user)
     "hey there #{user.name}"
@@ -147,13 +147,13 @@ class API < Grape::API
     say_hello(current_user)
   end
 end
-````
+```
 
 ## Cookies
 
 You can set, get and delete your cookies very simply using `cookies` method:
 
-````ruby
+``` ruby
 class API < Grape::API
   get '/counter' do
     cookies[:counter] ||= 0
@@ -165,32 +165,32 @@ class API < Grape::API
     { :result => cookies.delete(:counter) }
   end
 end
-````
+```
 
 To set more than value use hash-based syntax:
 
-````ruby
+``` ruby
 cookies[:counter] = {
     :value => 0,
     :expires => Time.tomorrow,
     :domain => '.example.com',
     :path => '/'
 }
 cookies[:counter][:value] +=1
-````
+```
 
 ## Raising Errors
 
 You can raise errors explicitly.
 
-```ruby
+``` ruby
 error!("Access Denied", 401)
 ```
 
 You can also return JSON formatted objects explicitly by raising error! and
 passing a hash instead of a message.
 
-```ruby
+``` ruby
 error!({ "error" => "unexpected error", "detail" => "missing widget" }, 500)
 ```
 
@@ -199,15 +199,15 @@ error!({ "error" => "unexpected error", "detail" => "missing widget" }, 500)
 Grape can be told to rescue all exceptions and instead return them in
 text or json formats.
 
-```ruby
+``` ruby
 class Twitter::API < Grape::API
   rescue_from :all
 end
 ```
 
 You can also rescue specific exceptions.
 
-```ruby
+``` ruby
 class Twitter::API < Grape::API
   rescue_from ArgumentError, NotImplementedError
 end
@@ -216,7 +216,7 @@ end
 The error format can be specified using `error_format`. Available formats are
 `:json` and `:txt` (default).
 
-```ruby
+``` ruby
 class Twitter::API < Grape::API
   error_format :json
 end
@@ -225,7 +225,7 @@ end
 You can rescue all exceptions with a code block. The `rack_response` wrapper
 automatically sets the default error code and content-type.
 
-```ruby
+``` ruby
 class Twitter::API < Grape::API
   rescue_from :all do |e|
     rack_response({ :message => "rescued from #{e.class.name}" })
@@ -236,43 +236,60 @@ end
 You can also rescue specific exceptions with a code block and handle the Rack
 response at the lowest level.
 
-```ruby
+``` ruby
 class Twitter::API < Grape::API
   rescue_from :all do |e|
     Rack::Response.new([ e.message ], 500, { "Content-type" => "text/error" }).finish
   end
 end
 ```
 
-    class Twitter::API < Grape::API
-      rescue_from ArgumentError do |e|
-        Rack::Response.new([ "ArgumentError: #{e.message}" ], 500)
-      end
-      rescue_from NotImplementedError do |e|
-        Rack::Response.new([ "NotImplementedError: #{e.message}" ], 500)
-      end
-    end
+``` ruby
+class Twitter::API < Grape::API
+  rescue_from ArgumentError do |e|
+    Rack::Response.new([ "ArgumentError: #{e.message}" ], 500)
+  end
+  rescue_from NotImplementedError do |e|
+    Rack::Response.new([ "NotImplementedError: #{e.message}" ], 500)
+  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 
+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
+``` ruby
 class Twitter::API < Grape::API
   content_type :xls, "application/vnd.ms-excel"
 end
 ```
 
+You can also set the default format. 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 format, if specified by the `format` option.
+* 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
+class Twitter::API < Grape::API
+  format :json
+  default_format :json
+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`.
 
-```ruby
+``` ruby
 RSpec.configure do |config|
   config.include RSpec::Rails::RequestExampleGroup, :type => :request, :example_group => {
     :file_path => /spec\/api/
@@ -282,7 +299,7 @@ end
 
 A simple RSpec API test makes a `get` request and parses the response.
 
-```ruby
+``` ruby
 require 'spec_helper'
 
 describe Twitter::API do
@@ -299,10 +316,10 @@ 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. 
+elements that can also be inspected at runtime.
 This can be useful for generating documentation.
 
-```ruby
+``` ruby
 class TwitterAPI < Grape::API
 
   version 'v1'
@@ -327,7 +344,7 @@ contains a `route_prefix`, `route_version`, `route_namespace`, `route_method`,
 follows the API path may contain any number of keys and its values are also
 accessible via dynamically-generated `route_[name]` functions.
 
-```ruby
+``` ruby
 TwitterAPI::versions # yields [ 'v1', 'v2' ]
 TwitterAPI::routes # yields an array of Grape::Route objects
 TwitterAPI::routes[0].route_version # yields 'v1'
@@ -336,7 +353,7 @@ TwitterAPI::routes[0].route_description # yields [ { "s" => { :desc => "string t
 
 Parameters can also be tagged to the method declaration itself.
 
-```ruby
+``` ruby
 class StringAPI < Grape::API
   get "split/:string", { :params => [ "token" ], :optional_params => [ "limit" ] } do
     params[:string].split(params[:token], (params[:limit] || 0))
@@ -349,7 +366,7 @@ StringAPI::routes[0].route_optional_params # yields an array [ "limit" ]
 
 It's possible to retrieve the information about the current route from within an API call with `route`.
 
-```ruby
+``` ruby
 class MyAPI < Grape::API
   desc "Returns a description of a parameter.", { :params => { "id" => "a required id" } }
   get "params/:id" do
@@ -372,7 +389,7 @@ 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
+``` ruby
 class UrlAPI < Grape::API
   namespace :urls do
     get '/(*:url)', :anchor => false do
@@ -403,5 +420,5 @@ MIT License. See LICENSE for details.
 
 ## Copyright
 
-Copyright (c) 2010-2012 Michael Bleigh and Intridea, Inc. 
+Copyright (c) 2010-2012 Michael Bleigh and Intridea, Inc.
 

lib/grape/api.rb

@@ -109,13 +109,18 @@ def desc(description, options = {})
         @last_description = options.merge(:description => description)
       end
 
-      # Specify the default format for the API's
-      # serializers. Currently only `:json` is
-      # supported.
+      # Specify the default format for the API's serializers.
+      # May be `:json` or `:txt` (default).
       def default_format(new_format = nil)
         new_format ? set(:default_format, new_format.to_sym) : settings[:default_format]
       end
 
+      # Specify the format for the API's serializers.
+      # May be `:json` or `:txt`.
+      def format(new_format = nil)
+        new_format ? set(:format, new_format.to_sym) : settings[:format]
+      end
+      
       # Specify the format for error messages.
       # May be `:json` or `:txt` (default).
       def error_format(new_format = nil)

lib/grape/endpoint.rb

@@ -273,9 +273,10 @@ def build_middleware
           :version_options => settings[:version_options]
         }
       end
-
+      
       b.use Grape::Middleware::Formatter,
-        :default_format => settings[:default_format] || :json,
+        :format => settings[:format],
+        :default_format => settings[:default_format] || :txt,
         :content_types => settings[:content_types]
 
       aggregate_setting(:middleware).each do |m|

lib/grape/middleware/formatter.rb

@@ -6,7 +6,7 @@ class Formatter < Base
       include Formats
 
       def default_options
-        { 
+        {
           :default_format => :txt,
           :formatters => {},
           :content_types => {},
@@ -19,7 +19,7 @@ def headers
       end
 
       def before
-        fmt = format_from_extension || format_from_header || options[:default_format]
+        fmt = format_from_extension || options[:format] || format_from_header || options[:default_format]
         if content_types.key?(fmt)
           if !env['rack.input'].nil? and (body = env['rack.input'].read).strip.length != 0
             parser = parser_for fmt
@@ -52,7 +52,7 @@ def format_from_extension
       end
 
       def format_from_header
-        mime_array.each do |t| 
+        mime_array.each do |t|
           if mime_types.key?(t)
             return mime_types[t]
           end