grape 0.7.0 → 0.8.0

checksums.yaml

@@ -1,15 +1,7 @@
 ---
-!binary "U0hBMQ==":
-  metadata.gz: !binary |-
-    NzU0ZDEzNjI0ZDhlMzg5M2YxOTMzMmU2NmUxMWIyZDYxMGM3ODBiNQ==
-  data.tar.gz: !binary |-
-    NmMwYmIxODY2ZmI0YzY5MzljYTM0NWE5MDM4MzAwZDQ3M2Y4MmYwNg==
+SHA1:
+  metadata.gz: 16ab2241d8805f0449737830d3fb60b5ecf6a1e3
+  data.tar.gz: b2d2d3cce8167bac238d0d8ac770edac583b0a81
 SHA512:
-  metadata.gz: !binary |-
-    ODgwYzYzMzlkNzJjMTgyYzkyMmQ3ZDhlNWEyNDRmMGNiZDMxZDI4NDIzZGRk
-    NzEwNjdjYjI0MzkzNzE1M2QwM2ExZGM2NDRlMmFlNDJlZWY3NjljMGMxN2Zm
-    OWNkMGM0ZGFkMDQwYzk1MDBlNDZkNjI4ZmJmZjM4M2Y3MmU4NDI=
-  data.tar.gz: !binary |-
-    N2Y5Y2NhNWQxMjNmYmZmMzJhZDQyMzE2NDY1ODRlNjVhNDc2ZjQxNTE4NjRl
-    YzczZTk5NGUwZGQ1ZmJiNTUwNmQ5MTM1ZWVkNzA0M2JlNDZhNGVkM2MyNTM5
-    Zjg2MzhkNGI5YjMxNzRlNWUyZDg1YzA2NjY4MjdkMWE4MTU1N2Y=
+  metadata.gz: ead66bb7118fdb6c173dcb4e9459a6385cd1ea984738e60c23754ff1c508d8562ff8d0a161ac7bebd14ec9afc22fd73170b7f15324facfc1ce79e6688d0a2d5b
+  data.tar.gz: 10be3eceb5dcd72fcf5952d4d8bac3fa0eb9eb1a3eb5f08fa14486a2e24dcf21b578886dc314f09b6227d12214fa8ba9326f488405e2082acf1397e397d24d88

data/.rubocop.yml

@@ -1,5 +1,5 @@
 AllCops:
-  Excludes:
+  Exclude:
     - vendor/**
     - bin/**
 
@@ -24,11 +24,6 @@ Encoding:
   # no need to always specify encoding
   Enabled: false
 
-HashMethods:
-  # key? instead of has_key?
-  # value? instead of has_value?
-  Enabled: false
-
 StringLiterals:
   # use single or double-quoted strings, as you please
   Enabled: false
@@ -68,3 +63,8 @@ WordArray:
 CyclomaticComplexity:
   Enabled: false
 
+DoubleNegation:
+  Enabled: false
+
+PredicateName:
+  Enabled: false

data/.travis.yml

@@ -1,9 +1,18 @@
 language: ruby
+
 cache: bundler
-before_install:
-  - gem install bundler -v '= 1.5.1'
+
 rvm:
+  - ruby-head
+  - 2.1.2
   - 2.1.0
   - 2.0.0
   - 1.9.3
   - jruby-19mode
+  - jruby-head
+  - rbx-2
+
+matrix:
+  allow_failures:
+    - rvm: ruby-head
+    - rvm: jruby-head

data/CHANGELOG.md

@@ -1,7 +1,29 @@
-0.7.0 (4/2/2013)
+0.8.0 (7/10/2014)
 =================
 
 #### Features
+
+* [#639](https://github.com/intridea/grape/pull/639): Added support for blocks with reusable params - [@mibon](https://github.com/mibon).
+* [#637](https://github.com/intridea/grape/pull/637): Added 'exactly_one_of' validation - [@Morred](https://github.com/Morred).
+* [#626](https://github.com/intridea/grape/pull/626): Mutually exclusive params - [@oliverbarnes](https://github.com/oliverbarnes).
+* [#617](https://github.com/intridea/grape/pull/617): Running tests on Ruby 2.1.1, Rubinius 2.1 and 2.2, Ruby and JRuby HEAD - [@dblock](https://github.com/dblock).
+* [#397](https://github.com/intridea/grape/pull/397): Adds `Grape::Endpoint.before_each` to allow easy helper stubbing - [@mbleigh](https://github.com/mbleigh).
+* [#673](https://github.com/intridea/grape/pull/673): Avoid requiring non-existent fields when using Grape::Entity documentation - [@qqshfox](https://github.com/qqshfox).
+
+#### Fixes
+
+* [#671](https://github.com/intridea/grape/pull/671): Allow required param with predefined set of values to be nil inside optional group - [@dm1try](https://github.com/dm1try).
+* [#651](https://github.com/intridea/grape/pull/651): The `rescue_from` keyword now properly defaults to rescuing subclasses of exceptions - [@xevix](https://github.com/xevix).
+* [#614](https://github.com/intridea/grape/pull/614): Params with `nil` value are now refused by `RegexpValidator` - [@dm1try](https://github.com/dm1try).
+* [#494](https://github.com/intridea/grape/issues/494): Fixed performance issue with requests carrying a large payload - [@dblock](https://github.com/dblock).
+* [#619](https://github.com/intridea/grape/pull/619): Convert specs to RSpec 3 syntax with Transpec - [@danielspector](https://github.com/danielspector).
+* [#632](https://github.com/intridea/grape/pull/632): `Grape::Endpoint#present` causes ActiveRecord to make an extra query during entity's detection - [@fixme](https://github.com/fixme).
+
+0.7.0 (4/2/2014)
+=================
+
+#### Features
+
 * [#558](https://github.com/intridea/grape/pull/558): Support lambda-based values for params - [@wpschallenger](https://github.com/wpschallenger).
 * [#510](https://github.com/intridea/grape/pull/510): Support lambda-based default values for params - [@myitcv](https://github.com/myitcv).
 * [#511](https://github.com/intridea/grape/pull/511): Added `required` option for OAuth2 middleware - [@bcm](https://github.com/bcm).

data/Gemfile

@@ -3,18 +3,19 @@ source 'http://rubygems.org'
 gemspec
 
 group :development, :test do
-  gem 'pry'
-  gem 'guard'
-  gem 'guard-rspec'
-  gem 'guard-bundler'
-  gem 'rb-fsevent'
-  gem 'growl'
-  gem 'json'
   gem 'rspec', '~> 2.14.1'
   gem 'rack-test', '~> 0.6.2', require: 'rack/test'
-  gem 'github-markup'
   gem 'cookiejar'
   gem 'rack-contrib'
-  gem 'redcarpet', platforms: :ruby
-  gem 'rubocop', '~> 0.15.0'
+  gem 'rubocop', '~> 0.20.1'
+  gem 'guard'
+  gem 'guard-rspec'
+  gem 'guard-rubocop'
+  gem 'mime-types'
+end
+
+platforms :rbx do
+  gem 'rubysl'
+  gem 'rubinius-developer_tools'
+  gem 'racc'
 end

data/Guardfile

@@ -1,15 +1,14 @@
 # A sample Guardfile
 # More info at https://github.com/guard/guard#readme
 
-guard 'rspec', :version => 2 do
+guard :rspec do
   watch(%r{^spec/.+_spec\.rb$})
   watch(%r{^lib/(.+)\.rb$})     { |m| "spec/#{m[1]}_spec.rb" }
-  watch(%r{^spec/support/shared_versioning_examples.rb$}) { |m| "spec/" }
-  watch('spec/spec_helper.rb')  { "spec/" }
+  watch('spec/spec_helper.rb')  { "spec" }
 end
 
 
-guard 'bundler' do
-  watch('Gemfile')
-  watch(/^.+\.gemspec/)
+guard :rubocop do
+  watch(%r{.+\.rb$})
+  watch(%r{(?:.+/)?\.rubocop\.yml$}) { |m| File.dirname(m[0]) }
 end

data/README.md

@@ -1,4 +1,70 @@
-![grape logo](https://github.com/intridea/grape/wiki/grape_logo.png)
+![grape logo](grape.png)
+
+[![Build Status](https://travis-ci.org/intridea/grape.png?branch=master)](http://travis-ci.org/intridea/grape) [![Code Climate](https://codeclimate.com/github/intridea/grape.png)](https://codeclimate.com/github/intridea/grape) [![Inline docs](http://inch-ci.org/github/intridea/grape.png)](http://inch-ci.org/github/intridea/grape) [![Dependency Status](https://www.versioneye.com/ruby/grape/0.7.0/badge.png)](https://www.versioneye.com/ruby/grape/0.7.0)
+
+## Table of Contents
+
+- [What is Grape?](#what-is-grape)
+- [Stable Release](#stable-release)
+- [Project Resources](#project-resources)
+- [Installation](#installation)
+- [Basic Usage](#basic-usage)
+- [Mounting](#mounting)
+  - [Rack](#rack)
+  - [Alongside Sinatra (or other frameworks)](#alongside-sinatra-or-other-frameworks)
+  - [Rails](#rails)
+  - [Modules](#modules)
+- [Versioning](#versioning)
+  - [Path](#path)
+  - [Header](#header)
+  - [Accept-Version Header](#accept-version-header)
+  - [Param](#param)
+- [Describing Methods](#describing-methods)
+- [Parameters](#parameters)
+- [Parameter Validation and Coercion](#parameter-validation-and-coercion)
+  - [Namespace Validation and Coercion](#namespace-validation-and-coercion)
+  - [Custom Validators](#custom-validators)
+  - [Validation Errors](#validation-errors)
+  - [I18n](#i18n)
+- [Headers](#headers)
+- [Routes](#routes)
+- [Helpers](#helpers)
+- [Parameter Documentation](#parameter-documentation)
+- [Cookies](#cookies)
+- [Redirecting](#redirecting)
+- [Allowed Methods](#allowed-methods)
+- [Raising Exceptions](#raising-exceptions)
+  - [Default Error HTTP Status Code](#default-error-http-status-code)
+  - [Handling 404](#handling-404)
+- [Exception Handling](#exception-handling)
+  - [Rails 3.x](#rails-3x)
+- [Logging](#logging)
+- [API Formats](#api-formats)
+  - [JSONP](#jsonp)
+  - [CORS](#cors)
+- [Content-type](#content-type)
+- [API Data Formats](#api-data-formats)
+- [RESTful Model Representations](#restful-model-representations)
+  - [Grape Entities](#grape-entities)
+  - [Hypermedia](#hypermedia)
+  - [Rabl](#rabl)
+  - [Active Model Serializers](#active-model-serializers)
+- [Authentication](#authentication)
+- [Describing and Inspecting an API](#describing-and-inspecting-an-api)
+- [Current Route and Endpoint](#current-route-and-endpoint)
+- [Before and After](#before-and-after)
+- [Anchoring](#anchoring)
+- [Writing Tests](#writing-tests)
+  - [Writing Tests with Rack](#writing-tests-with-rack)
+  - [Writing Tests with Rails](#writing-tests-with-rails)
+  - [Stubbing Helpers](#stubbing-helpers)
+- [Reloading API Changes in Development](#reloading-api-changes-in-development)
+  - [Rails 3.x](#rails-3x)
+- [Performance Monitoring](#performance-monitoring)
+- [Contributing to Grape](#contributing-to-grape)
+- [Hacking on Grape](#hacking-on-grape)
+- [License](#license)
+- [Copyright](#copyright)
 
 ## What is Grape?
 
@@ -8,11 +74,10 @@ 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) [![Code Climate](https://codeclimate.com/github/intridea/grape.png)](https://codeclimate.com/github/intridea/grape) [![Inline docs](http://inch-pages.github.io/github/intridea/grape.png)](http://inch-pages.github.io/github/intridea/grape) [![Dependency Status](https://www.versioneye.com/ruby/grape/0.6.1/badge.png)](https://www.versioneye.com/ruby/grape/0.6.1)
-
 ## Stable Release
 
-You're reading the documentation for the stable release of Grape, 0.7.0.
+You're reading the documentation for the stable release of Grape, 0.8.0.
+Please read [UPGRADING](UPGRADING.md) when upgrading from a previous version.
 
 ## Project Resources
 
@@ -164,7 +229,9 @@ run Rack::Cascade.new [API, Web]
 
 ### Rails
 
-Place API files into `app/api` and modify `application.rb`.
+Place API files into `app/api`. Rails expects a subdirectory that matches the name of the Ruby module and a file name that matches the name of the class. In our example, the file name location and directory for `Twitter::API` should be `app/api/twitter/api.rb`.
+
+Modify `application.rb`:
 
 ```ruby
 config.paths.add File.join('app', 'api'), glob: File.join('**', '*.rb')
@@ -345,6 +412,7 @@ params do
   optional :audio do
     requires :format, type: Symbol, values: [:mp3, :wav, :aac, :ogg], default: :mp3
   end
+  mutually_exclusive :media, :audio
 end
 put ':id' do
   # params[:id] is an Integer
@@ -406,6 +474,41 @@ params do
 end
 ```
 
+Parameters can be defined as `mutually_exclusive`, ensuring that they aren't present at the same time in a request.
+
+```ruby
+params do
+  optional :beer
+  optional :wine
+  mutually_exclusive :beer, :wine
+end
+```
+
+Multiple sets can be defined:
+
+```ruby
+params do
+  optional :beer
+  optional :wine
+  mutually_exclusive :beer, :wine
+  optional :scotch
+  optional :aquavit
+  mutually_exclusive :scotch, :aquavit
+end
+```
+
+**Warning**: Never define mutually exclusive sets with any required params. Two mutually exclusive required params will mean params are never valid, thus making the endpoint useless. One required param mutually exclusive with an optional param will mean the latter is never valid.
+
+Parameters can be defined as 'exactly_one_of', ensuring that exactly one parameter gets selected.
+
+```ruby
+params do
+  optional :beer
+  optional :wine
+  exactly_one_of :beer, :wine
+end
+```
+
 ### Namespace Validation and Coercion
 
 Namespaces allow parameter definitions and apply to every method within the namespace.
@@ -624,13 +727,43 @@ end
 class API < Grape::API
   helpers SharedParams
 
-  desc "Get collection"
+  desc "Get collection."
   params do
     use :period, :pagination
   end
+
   get do
-    Collection.from(params[:start_date]).to(params[:end_date])
-              .page(params[:page]).per(params[:per_page])
+    Collection
+      .from(params[:start_date])
+      .to(params[:end_date])
+      .page(params[:page])
+      .per(params[:per_page])
+  end
+end
+```
+
+Helpers support blocks that can help set default values. The following API can return a collection sorted by `id` or `created_at` in `asc` or `desc` order.
+
+```ruby
+module SharedParams
+  extend Grape::API::Helpers
+
+  params :order do |options|
+    optional :order_by, type:Symbol, values:options[:order_by], default:options[:default_order_by]
+    optional :order, type:Symbol, values:%i(asc desc), default:options[:default_order]
+  end
+end
+
+class API < Grape::API
+  helpers SharedParams
+
+  desc "Get a sorted collection."
+  params do
+    use :order, order_by:%i(id created_at), default_order_by: :created_at, default_order: :asc
+  end
+
+  get do
+    Collection.send(params[:order], params[:order_by])
   end
 end
 ```
@@ -911,7 +1044,7 @@ The code below will rescue exceptions of type `RuntimeError` but _not_ its subcl
 
 ```ruby
 rescue_from RuntimeError, rescue_subclasses: false do |e|
-    Rack::Response.new(
+    Rack::Response.new({
       status: e.status,
       message: e.message,
       errors: e.errors
@@ -1072,6 +1205,21 @@ The order for choosing the format is the following.
 * Use the default format, if specified by the `default_format` option.
 * Default to `:txt`.
 
+You can override this process explicitly by specifying `env['api.format']` in the API itself.
+For example, the following API will let you upload arbitrary files and return their contents as an attachment with the correct MIME type.
+
+```ruby
+class Twitter::API < Grape::API
+  post "attachment" do
+    filename = params[:file][:filename]
+    content_type MIME::Types.type_for(filename)[0].to_s
+    env['api.format'] = :binary # there's no formatter for :binary, data will be returned "as is"
+    header "Content-Disposition", "attachment; filename*=UTF-8''#{URI.escape(filename)}"
+    params[:file][:tempfile].read
+  end
+end
+```
+
 ### JSONP
 
 Grape supports JSONP via [Rack::JSONP](https://github.com/rack/rack-contrib), part of the
@@ -1183,7 +1331,7 @@ module API
       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 :user_type, :user_id, if: lambda { |status, options| status.user.public? }
       expose :digest { |status, options| Digest::MD5.hexdigest(status.txt) }
       expose :replies, using: API::Status, as: :replies
     end
@@ -1211,9 +1359,10 @@ module API
   class Statuses < Grape::API
     version 'v1'
 
-    desc 'Create a status', {
+    desc 'Create a status'
+    params do
       requires :all, except: [:ip], using: API::Entities::Status.documentation.except(:id)
-    }
+    end
     post '/status' do
       Status.create! params
     end
@@ -1450,7 +1599,7 @@ 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:
+For instance when your API needs to get part of an URL, for instance:
 
 ```ruby
 class TwitterAPI < Grape::API
@@ -1540,6 +1689,31 @@ RSpec.configure do |config|
 end
 ```
 
+### Stubbing Helpers
+
+Because helpers are mixed in based on the context when an endpoint is defined, it can
+be difficult to stub or mock them for testing. The `Grape::Endpoint.before_each` method
+can help by allowing you to define behavior on the endpoint that will run before every
+request.
+
+```ruby
+describe 'an endpoint that needs helpers stubbed' do
+  before do
+    Grape::Endpoint.before_each do |endpoint|
+      endpoint.stub(:helper_name).and_return('desired_value')
+    end
+  end
+
+  after do
+    Grape::Endpoint.before_each nil
+  end
+
+  it 'should properly stub the helper' do
+    # ...
+  end
+end
+```
+
 ## Reloading API Changes in Development
 
 ### Rails 3.x
@@ -1583,6 +1757,13 @@ features and discuss issues.
 
 See [CONTRIBUTING](CONTRIBUTING.md).
 
+## Hacking on Grape
+
+You can start hacking on Grape on
+[Nitrous.IO](https://www.nitrous.io/?utm_source=github.com&utm_campaign=grape&utm_medium=hackonnitrous) in a matter of seconds:
+
+[![Hack intridea/grape on Nitrous.IO](https://d3o0mnbgv6k92a.cloudfront.net/assets/hack-l-v1-3cc067e71372f6045e1949af9d96095b.png)](https://www.nitrous.io/hack_button?source=embed&runtime=rails&repo=intridea%2Fgrape&file_to_open=README.md)
+
 ## License
 
 MIT License. See LICENSE for details.