versioncake 2.5.0 → 3.0.0

checksums.yaml

@@ -1,15 +1,7 @@
 ---
-!binary "U0hBMQ==":
-  metadata.gz: !binary |-
-    N2VhZjA2ZWU5ODU0MWVhYTQ4Nzk1NmM1OTFjNmIzYzJjZGUwZGQ5OQ==
-  data.tar.gz: !binary |-
-    M2RhOTQ5YzNiODAzY2JkMzg2NjMzM2UwMDllNjdjMjBiNjVjNDgzNg==
-!binary "U0hBNTEy":
-  metadata.gz: !binary |-
-    NmJiMzc5YTk5MjcwODU2MTI0M2YzOGIxYTlhM2EwOWJjZDRjYzJiOWJjMDIz
-    MzJmOTA0NjFhMzlhM2I5ODMyMzE4YWYzNzc5ZTMzMWNkMGJjZDdjY2RjNzE4
-    ODc4NDE0MmU1ZmY2ZjM1ZDc1ZmJiMTg4ZWVhODViMGU3MjkxOGE=
-  data.tar.gz: !binary |-
-    MWExYWQ1ZmI5ZThlN2Q4N2QwNTg5NDU4NzM5MzdlODQ5NzFiODczNjIxMTM1
-    MzUzYjQ1OGRlMTVhNDM1MmRlMWRmMDY4NzYyNTRjYzIxZDFjZTM1YTkyYjhm
-    ZTkxMWM2YTNkZmEyYTdhOTEzNzZlOTk5MjI3NDJlZjZmYjJjMmM=
+SHA1:
+  metadata.gz: b2f2076334af038794b17f3f6cae1e2c0fb8347d
+  data.tar.gz: 8f6fc9bf8359ba05b5e7f0620c280aa2ead43f47
+SHA512:
+  metadata.gz: 12c7dbe459aeb4a7caff6599905bc52f90a40a32a0220492d133a89f394a2791cce96abcfad434fd32cc3ccd477d59bd95cf8a86432e1f469769f925bea85fc6
+  data.tar.gz: 4394f668996b75d5b5ae627c895eeb5a0a45c0f096b51f1370acfacd4a458b5e68c529ee5643bae0c64e4f900630a68bda728a2e59a61e8cca7e329a5ccd72d1

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--format=progress

data/.travis.yml

@@ -4,12 +4,14 @@ rvm:
   - 1.9.3
   - 2.0.0
   - 2.1.0
+  - 2.2.0
   - ruby-head
 
 gemfile:
   - gemfiles/rails3.2.gemfile
   - gemfiles/rails4.0.gemfile
   - gemfiles/rails4.1.gemfile
+  - gemfiles/rails4.2.gemfile
 
 matrix:
   exclude:
@@ -17,6 +19,8 @@ matrix:
       gemfile: gemfiles/rails4.0.gemfile
     - rvm: 1.9.2
       gemfile: gemfiles/rails4.1.gemfile
+    - rvm: 1.9.2
+      gemfile: gemfiles/rails4.2.gemfile
 
   allow_failures:
     - rvm: ruby-head

data/Appraisals

@@ -2,12 +2,18 @@ appraise "rails3.2" do
   gem('actionpack',     '~> 3.2.0')
   gem('activesupport',  '~> 3.2.0')
   gem('railties',       '~> 3.2.0')
+  # Rails 3.2 has test-unit as a dependency, but Ruby 2.2 removes
+  # it, so we need to now manually require it as a dependency
+  gem('test-unit',       '~>3.0')
 end
 
 appraise "rails4.0" do
   gem('actionpack',     '~> 4.0.0')
   gem('activesupport',  '~> 4.0.0')
   gem('railties',       '~> 4.0.0')
+  # Rails 4.0 has test-unit as a dependency, but Ruby 2.2 removes
+  # it, so we need to now manually require it as a dependency
+  gem('test-unit',       '~>3.0')
 end
 
 appraise "rails4.1" do
@@ -15,3 +21,9 @@ appraise "rails4.1" do
   gem('activesupport',  '~> 4.1.0')
   gem('railties',       '~> 4.1.0')
 end
+
+appraise "rails4.2" do
+  gem('actionpack',     '~> 4.2.0')
+  gem('activesupport',  '~> 4.2.0')
+  gem('railties',       '~> 4.2.0')
+end

data/CHANGELOG.md

@@ -1,6 +1,6 @@
 ## Unreleased Changes
 
-[Full Changelog](https://github.com/bwillis/versioncake/compare/v2.5...master)
+[Full Changelog](https://github.com/bwillis/versioncake/compare/v3.0...master)
 
 Bug Fixes:
 
@@ -14,6 +14,23 @@ Deprecations:
 
 * None
 
+## 3.0.0 (Aug 3, 2015)
+
+Bug Fixes:
+
+* When an invalid version is received an unsupported exception is raised (#34)
+* Remove deprecated X- from header (breaking change)
+* Remove warning in Rails 5 (#40) Thanks [Michael Elfassy](https://github.com/elfassy)!
+
+Enhancements:
+
+* Migrate from test-unit to rspec (#37)
+* Rack based versioning middleware (#36) (breaking changes)
+
+Deprecations:
+
+* None
+
 ## 2.5.0 (Apr 18, 2014)
 
 [Full Changelog](https://github.com/bwillis/versioncake/compare/v2.4...v2.5)

data/CONTRIBUTING.md

@@ -14,5 +14,5 @@ We really like when people not only discover something they want added/fixed/rem
 
 Version Cake supports multiple versions of Rails with Appriasals. These will be automatically tested against several ruby versions on CI. If you need to debug a problem, or want to be dilegent and run all of these do the following:
 
-* Install the gems for all supported Rails versions: `bundle exec rake appraisal:install`
-* Run all the tests for the supported Rails versions: `bundle exec rake appraisal test`
+* Install the gems for all supported Rails versions: `bundle exec rake appraisal install`
+* Run all the tests for the supported Rails versions: `bundle exec rake appraisal spec`

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    versioncake (2.5.0)
+    versioncake (3.0.0)
       actionpack (>= 3.2)
       activesupport (>= 3.2)
       railties (>= 3.2)
@@ -10,61 +10,110 @@ PATH
 GEM
   remote: https://rubygems.org/
   specs:
-    actionpack (4.1.0)
-      actionview (= 4.1.0)
-      activesupport (= 4.1.0)
-      rack (~> 1.5.2)
+    actionpack (4.2.3)
+      actionview (= 4.2.3)
+      activesupport (= 4.2.3)
+      rack (~> 1.6)
       rack-test (~> 0.6.2)
-    actionview (4.1.0)
-      activesupport (= 4.1.0)
+      rails-dom-testing (~> 1.0, >= 1.0.5)
+      rails-html-sanitizer (~> 1.0, >= 1.0.2)
+    actionview (4.2.3)
+      activesupport (= 4.2.3)
       builder (~> 3.1)
       erubis (~> 2.7.0)
-    activesupport (4.1.0)
-      i18n (~> 0.6, >= 0.6.9)
+      rails-dom-testing (~> 1.0, >= 1.0.5)
+      rails-html-sanitizer (~> 1.0, >= 1.0.2)
+    activesupport (4.2.3)
+      i18n (~> 0.7)
       json (~> 1.7, >= 1.7.7)
       minitest (~> 5.1)
-      thread_safe (~> 0.1)
+      thread_safe (~> 0.3, >= 0.3.4)
       tzinfo (~> 1.1)
-    appraisal (0.5.2)
+    appraisal (2.0.2)
       bundler
       rake
+      thor (>= 0.14.0)
     builder (3.2.2)
-    colorize (0.5.8)
-    coveralls (0.6.7)
-      colorize
-      multi_json (~> 1.3)
-      rest-client
-      simplecov (>= 0.7)
-      thor
+    coveralls (0.8.2)
+      json (~> 1.8)
+      rest-client (>= 1.6.8, < 2)
+      simplecov (~> 0.10.0)
+      term-ansicolor (~> 1.3)
+      thor (~> 0.19.1)
+    diff-lcs (1.2.5)
+    docile (1.1.5)
+    domain_name (0.5.24)
+      unf (>= 0.0.5, < 1.0.0)
     erubis (2.7.0)
-    i18n (0.6.9)
-    json (1.8.1)
-    metaclass (0.0.1)
-    mime-types (1.23)
-    minitest (5.3.3)
-    mocha (0.14.0)
-      metaclass (~> 0.0.1)
-    multi_json (1.9.2)
-    rack (1.5.2)
-    rack-test (0.6.2)
+    http-cookie (1.0.2)
+      domain_name (~> 0.5)
+    i18n (0.7.0)
+    json (1.8.3)
+    loofah (2.0.2)
+      nokogiri (>= 1.5.9)
+    mime-types (2.6.1)
+    mini_portile (0.6.2)
+    minitest (5.7.0)
+    netrc (0.10.3)
+    nokogiri (1.6.6.2)
+      mini_portile (~> 0.6.0)
+    rack (1.6.4)
+    rack-test (0.6.3)
       rack (>= 1.0)
-    railties (4.1.0)
-      actionpack (= 4.1.0)
-      activesupport (= 4.1.0)
+    rails-deprecated_sanitizer (1.0.3)
+      activesupport (>= 4.2.0.alpha)
+    rails-dom-testing (1.0.6)
+      activesupport (>= 4.2.0.beta, < 5.0)
+      nokogiri (~> 1.6.0)
+      rails-deprecated_sanitizer (>= 1.0.1)
+    rails-html-sanitizer (1.0.2)
+      loofah (~> 2.0)
+    railties (4.2.3)
+      actionpack (= 4.2.3)
+      activesupport (= 4.2.3)
       rake (>= 0.8.7)
       thor (>= 0.18.1, < 2.0)
-    rake (10.0.4)
-    rest-client (1.6.7)
-      mime-types (>= 1.16)
-    simplecov (0.7.1)
-      multi_json (~> 1.0)
-      simplecov-html (~> 0.7.1)
-    simplecov-html (0.7.1)
-    test-unit (2.5.5)
-    thor (0.18.1)
-    thread_safe (0.3.3)
-    tzinfo (1.1.0)
+    rake (10.4.2)
+    rest-client (1.8.0)
+      http-cookie (>= 1.0.2, < 2.0)
+      mime-types (>= 1.16, < 3.0)
+      netrc (~> 0.7)
+    rspec (3.3.0)
+      rspec-core (~> 3.3.0)
+      rspec-expectations (~> 3.3.0)
+      rspec-mocks (~> 3.3.0)
+    rspec-core (3.3.2)
+      rspec-support (~> 3.3.0)
+    rspec-expectations (3.3.1)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.3.0)
+    rspec-mocks (3.3.2)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.3.0)
+    rspec-rails (3.3.3)
+      actionpack (>= 3.0, < 4.3)
+      activesupport (>= 3.0, < 4.3)
+      railties (>= 3.0, < 4.3)
+      rspec-core (~> 3.3.0)
+      rspec-expectations (~> 3.3.0)
+      rspec-mocks (~> 3.3.0)
+      rspec-support (~> 3.3.0)
+    rspec-support (3.3.0)
+    simplecov (0.10.0)
+      docile (~> 1.1.0)
+      json (~> 1.8)
+      simplecov-html (~> 0.10.0)
+    simplecov-html (0.10.0)
+    term-ansicolor (1.3.2)
+      tins (~> 1.0)
+    thor (0.19.1)
+    thread_safe (0.3.5)
+    tins (1.5.4)
+    tzinfo (1.2.2)
       thread_safe (~> 0.1)
+    unf (0.1.4)
+      unf_ext
+    unf_ext (0.0.7.1)
 
 PLATFORMS
   ruby
@@ -72,7 +121,10 @@ PLATFORMS
 DEPENDENCIES
   appraisal
   coveralls
-  mocha
   rake
-  test-unit
+  rspec
+  rspec-rails
   versioncake!
+
+BUNDLED WITH
+   1.10.6

data/README.md

@@ -29,18 +29,39 @@ Check out https://github.com/bwillis/350-rest-api-versioning for a comparison of
 
 ```
 gem install versioncake
+rails g versioncake:install
 ```
 
 ### Requirements
 
-| Version | Rails 3.2 Support? | Rails 4 Support? | Rails 4.1 Support? | [Rails API](https://github.com/rails-api/rails-api) 0.2 Support? |
-| ------- |:---------:| -------:| -------:| -------:|
-| [1.0](CHANGELOG.md#100-march-14-2013) | Yes       | No      | No      | No   |
-| [1.1](CHANGELOG.md#110-may-18-2013)   | Yes       | No      | No      | No   |
-| [1.2](CHANGELOG.md#120-may-26-2013)   | Yes       | Yes     | No      | No   |
-| [1.3](CHANGELOG.md#130-sept-26-2013)  | Yes       | Yes     | No      | No   |
-| [>2.0](CHANGELOG.md#200-feb-6-2014)   | Yes       | Yes     | Yes     | No   |
-| [>2.4](CHANGELOG.md#200-feb-6-2014)   | Yes       | Yes     | Yes     | Yes  |
+| Version | Rails 3.2 Support? | Rails 4 Support? | Rails >4.1 Support? | Rails >5 Support? | [Rails API](https://github.com/rails-api/rails-api) 0.2 Support? |
+| -------:|:---------:| -------:| -------:| -------:| -------:|
+| [1.0](CHANGELOG.md#100-march-14-2013) | Yes       | No      | No      | No   | No   |
+| [1.1](CHANGELOG.md#110-may-18-2013)   | Yes       | No      | No      | No   | No   |
+| [1.2](CHANGELOG.md#120-may-26-2013)   | Yes       | Yes     | No      | No   | No   |
+| [1.3](CHANGELOG.md#130-sept-26-2013)  | Yes       | Yes     | No      | No   | No   |
+| [>2.0](CHANGELOG.md#200-feb-6-2014)   | Yes       | Yes     | Yes     | No   | No   |
+| [>2.4](CHANGELOG.md#200-feb-6-2014)   | Yes       | Yes     | Yes     | No   | Yes  |
+| [>3.0](CHANGELOG.md)                  | Yes       | Yes     | Yes     | Yes  | Yes  |
+
+## Upgrade v2.0 -> v3.0
+
+### Accept header name changes
+
+The default accept header was changed from 'X-API-Version' to 'API-Version'. If you require the 'X-' or some other variant, you can specify a custom strategy as outlined in Extraction Strategy section below.
+
+### Configuration changes
+
+Configuration is now done with an initializer-you can generate a default one with `rails g versioncake:install` and then modify the generated file to match your configuration.
+
+### Configuration changes
+
+The configuration options for Version Cake have changed:
+
+| Old Name                                     | New Name               |
+| -------------------------------------------- | ---------------------- |
+| config.versioncake.supported_version_numbers | config.resources       |
+| config.versioncake.default_version           | config.missing_version |
 
 ## Upgrade v1.* -> v2.0
 
@@ -70,8 +91,13 @@ In this simple example we will outline the code that is introduced to support a
 
 ### config/application.rb
 ```ruby
-config.versioncake.supported_version_numbers = (1...4)
-config.versioncake.extraction_strategy       = :query_parameter # for simplicity
+VersionCake.setup do |config|
+  config.resources do |r|
+    r.resource %r{.*}, [], [], (1..4)
+  end
+  config.extraction_strategy = :query_parameter # for simplicity
+  config.missing_version = 4
+end
 ```
 
 Often times with APIs, depending upon the version, different logic needs to be applied. With the following controller code, the initial value of @posts includes all Post entries.
@@ -87,7 +113,7 @@ class PostsController < ApplicationController
     @posts = Post.scoped
 
     # version 3 or greated supports embedding post comments
-    if derived_version >= 3
+    if request_version >= 3
       @posts = @posts.includes(:comments)
     end
   end
@@ -160,7 +186,7 @@ For a given request, if we specify the version number, and that version of the v
 ```
 
 
-When no version is specified, the latest version of the view is rendered.  In this case, views/posts/index.json.v4.jbuilder.
+When no version is specified, the configured `missing_version` will be used to render a view.  In this case, views/posts/index.json.v4.jbuilder.
 
 #### http://localhost:3000/posts.json
 ```javascript
@@ -195,20 +221,28 @@ When no version is specified, the latest version of the view is rendered.  In th
 ## How to use
 
 ### Configuration
-The configuration should be placed in your Rails projects `config/application.rb`. It is also suggested to enable different settings per environment, for example development and test can have extraction strategies that make it easier to develop or write test code.
+The configuration lives in `config/initializers/versioncake.rb`.
 
-#### Supported Versions
-You need to define the supported versions in your Rails application.rb file as `view_versions`. Use this config to set the range of supported API versions that can be served:
+#### Versioned Resources
+Each individual resource uri can be identified by a regular expression. For each one it can be customized to have obsolete, deprecated, supported versions.
 
 ```ruby
-config.versioncake.supported_version_numbers = [1,2,3,4,5] # or (1..5)
+  config.resources do |r|
+    # r.resource uri_regex, obsolete, deprecated, supported
+
+    # version 2 and 3 are still supported on users resource
+    r.resource %r{/users}, [1], [2,3], [4]
+
+    # all other resources only allow v4
+    r.resource %r{.*}, [1,2,3], [], [4]
+  end
 ```
 
 #### Extraction Strategy
 
-You can also define the way to extract the version. The `view_version_extraction_strategy` allows you to set one of the default strategies or provide a proc to set your own. You can also pass it a prioritized array of the strategies.
+You can also define the way to extract the version. The `extraction_strategy` allows you to set one of the default strategies or provide a proc to set your own. You can also pass it a prioritized array of the strategies.
 ```ruby
-config.versioncake.extraction_strategy = :query_parameter # [:http_header, :http_accept_parameter]
+config.extraction_strategy = :query_parameter # [:http_header, :http_accept_parameter]
 ```
 These are the available strategies:
 
@@ -216,8 +250,8 @@ Strategy | Description | Example
 --- | --- | ---
 :query_parameter | version in the url query parameter, for testing or to override for special case | `http://localhost:3000/posts.json?api_version=1`  (This is the default.)
 :path_parameter | version in the url path parameter | `api/v:api_version/`
-request_parameter | version that is sent in the body of the request | Good for testing.
-:http_header | Api version HTTP header | `X-API-Version: 1`
+:request_parameter | version that is sent in the body of the request | Good for testing.
+:http_header | Api version HTTP header | `API-Version: 1`
 :http_accept_parameter | HTTP Accept header | `Accept: application/xml; version=1` [why do this?](http://blog.steveklabnik.com/posts/2011-07-03-nobody-understands-rest-or-http#i_want_my_api_to_be_versioned)
 custom | takes the request object and must return an integer | lambda {&#124;request&#124; request.headers["HTTP_X_MY_VERSION"].to_i } or class ExtractorStrategy; def execute(request);end;end
 
@@ -236,14 +270,20 @@ end
 
 When no version is supplied by a client, the version rendered will be the latest version by default. If you want to override this to another version, set the following property:
 ```ruby
-config.versioncake.default_version = 4
+config.missing_version = 4
 ```
 
 #### Version String
 
 The extraction strategies use a default string key of `api_version`, but that can be changed:
 ```ruby
-config.versioncake.version_key = "special_version_parameter_name"
+config.version_key = "special_version_parameter_name"
+```
+
+#### Version String
+If you do not wish to use the magic mapping of the version number to templates it can be disabled:
+```ruby
+config.rails_view_versioning = false
 ```
 
 ### Version your views
@@ -273,7 +313,7 @@ def index
   @posts = Post.scoped
 
   # version 3 or greated supports embedding post comments
-  if derived_version >= 3
+  if request_version >= 3
     @posts = @posts.includes(:comments)
   end
 end
@@ -282,9 +322,19 @@ end
 
 When a client makes a request it will automatically receive the latest supported version of the view. The client can also request for a specific version by one of the strategies configured by ``view_version_extraction_strategy``.
 
-### Unsupported Version Requests
+### Raised exceptions
+
+These are the types of exceptions VersionCake will raise:
+
+|Exception type|Description|
+|--------------|-----------|
+|VersionCake::UnsupportedVersionError| The version is invalid, too high or too low for the resource.|
+|VersionCake::ObsoleteVersionError|The version is obsolete for the resource.|
+|VersionCake::MissingVersionError|If no `config.missing_version` is specified, this will be raised when no version is in the request.|
+
+### Handling Exceptions
 
-If a client requests a version that is no longer supported (is not included in the `config.versioncake.supported_version_numbers`), a `VersionCake::UnsupportedVersionError` will be raised. This can be handled using Rails `rescue_from` to return app specific messages to the client.
+Handling exceptions can simply be done by using Rails `rescue_from` to return app specific messages to the client.
 
 ```ruby
 class ApplicationController < ActionController::Base
@@ -296,7 +346,7 @@ class ApplicationController < ActionController::Base
   private
 
   def render_unsupported_version
-    headers['X-API-Version-Supported'] = 'false'
+    headers['API-Version-Supported'] = 'false'
     respond_to do |format|
       format.json { render json: {message: "You requested an unsupported version (#{requested_version})"}, status: :unprocessable_entity }
     end
@@ -317,7 +367,7 @@ Testing can be painful but here are some easy ways to test different versions of
 Allowing more extraction strategies during testing can be helpful when needing to override the version.
 ```ruby
 # config/environments/test.rb
-config.versioncake.extraction_strategy = [:query_parameter, :request_parameter, :http_header, :http_accept_parameter]
+config.extraction_strategy = [:query_parameter, :request_parameter, :http_header, :http_accept_parameter]
 ```
 
 ### Testing a specific version
@@ -325,7 +375,7 @@ config.versioncake.extraction_strategy = [:query_parameter, :request_parameter,
 One way to test a specific version for would be to stub the requested version in the before block:
 ```ruby
 before do
-  @controller.stubs(:requested_version).returns(3)
+  @controller.stubs(:request_version).returns(3)
 end
 ```
 
@@ -343,7 +393,7 @@ end
 You can iterate over all of the supported version numbers by accessing the ```AppName::Application.config.versioncake.supported_version_numbers```.
 
 ```ruby
-AppName::Application.config.versioncake.supported_version_numbers.each do |supported_version|
+VersionCake.config.resources.first.supported_versions.each do |supported_version|
   before do
     @controller.stubs(:requested_version).returns(supported_version)
   end