versioncake 0.2.0 → 0.3.0

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    versioncake (0.1.0)
+    versioncake (0.3.0)
       actionpack (>= 3.0)
       activesupport (>= 3.0)
       railties (>= 3.0)

data/README.md

@@ -1,10 +1,23 @@
-# Version Cake [![Build Status](https://secure.travis-ci.org/bwillis/versioncake.png?branch=master)](http://travis-ci.org/bwillis/versioncake)
+![Version Cake](https://raw.github.com/alicial/versioncake/master/images/versioncake-logo450x100.png)
+
+[![Build Status](https://secure.travis-ci.org/bwillis/versioncake.png?branch=master)](http://travis-ci.org/bwillis/versioncake)
 
 Co-authored by Ben Willis ([@bwillis](https://github.com/bwillis/)) and Jim Jones ([@aantix](https://github.com/aantix)).
 
-Version Cake is an unobtrusive way to version views in your Rails app. 
+Version Cake is an unobtrusive way to version APIs in your Rails app. 
 
-We were tired of urls with version numbers, namespacing controllers with versions, and bumping all resources everytime we supported a new version. Simply configure your supported version numbers, create a versioned view if you need one and let versioncake render the requested version or gracefully degrade to the latest supported view version.
+- Easily version any view with their API version:
+
+```ruby
+app/views/posts/
+ - index.v1.xml.builder
+ - index.v3.xml.builder
+ - index.v1.json.jbuilder
+ - index.v4.json.jbuilder
+```
+- Gracefully degrade requests to the latest supported version
+- Clients can request API versions through different strategies
+- Dry your controller logic with exposed helpers
 
 ## Install
 
@@ -12,6 +25,134 @@ We were tired of urls with version numbers, namespacing controllers with version
 gem install versioncake
 ```
 
+## Example
+
+In this simple example we will outline the code that is introduced to support a change in a version.
+
+### config/application.rb
+```ruby
+config.view_versions = (1...4)
+config.view_version_extraction_strategy = :http_parameter # for simplicity
+```
+
+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.
+But if the requested API version is three or greater, we're going to eagerly load the associated comments as well.  
+
+Being able to control the logic based on the api version allow you to ensure forwards and backwards compatibility for future changes.
+
+### PostsController
+```ruby
+class PostsController < ApplicationController
+  def index
+    # shared code for all versions
+    @posts = Post.scoped
+
+    # version 3 or greated supports embedding post comments
+    if requested_version >= 3
+      @posts = @posts.includes(:comments)
+    end
+  end
+end
+```
+
+See the view samples below. The basic top level posts are referenced in views/posts/index.v1.json.jbuilder.
+But for views/posts/index.v4.json.jbuilder, we utilize the additional related comments.
+
+### Views
+
+Notice the version numbers are denoted by the "v{version number}" extension within the file name.
+
+#### views/posts/index.v1.json.jbuilder
+```ruby
+json.array!(@posts) do |json, post|
+    json.(post, :id, :title)
+end
+```
+
+#### views/posts/index.v4.json.jbuilder
+```ruby
+json.array!(@posts) do |json, post|
+    json.(post, :id, :title)
+    json.comments post.comments, :id, :text
+end
+```
+
+### Sample Output
+
+When a version is specified for which a view doesn't exist, the request degrades and renders the next lowest version number to ensure the API's backwards compatibility.  In the following case, since views/posts/index.v3.json.jbuilder doesn't exist, views/posts/index.v1.json.jbuilder is rendered instead.
+
+#### http://localhost:3000/posts.json?api_version=3 
+```javascript
+[
+  {
+    id: 1
+    title: "Version Cake v0.1.0 Released!"
+    name: "Ben"
+    updated_at: "2012-09-17T16:23:45Z"
+  },
+  {
+    id: 2
+    title: "Version Cake v0.2.0 Released!"
+    name: "Jim"
+    updated_at: "2012-09-17T16:23:32Z"
+  }
+]
+```
+
+
+For a given request, if we specify the version number, and that version of the view exists, that version specific view version will be rendered.  In the below case, views/posts/index.v1.json.jbuilder is rendered.
+
+#### http://localhost:3000/posts.json?api_version=2 or http://localhost:3000/posts.json?api_version=1 
+```javascript
+[
+  {
+    id: 1
+    title: "Version Cake v0.1.0 Released!"
+    name: "Ben"
+    updated_at: "2012-09-17T16:23:45Z"
+  },
+  {
+    id: 2
+    title: "Version Cake v0.2.0 Released!"
+    name: "Jim"
+    updated_at: "2012-09-17T16:23:32Z"
+  }
+]
+```
+
+
+When no version is specified, the latest version of the view is rendered.  In this case, views/posts/index.v4.json.jbuilder.
+
+#### http://localhost:3000/posts.json
+```javascript
+[
+  {
+    id: 1
+    title: "Version Cake v0.1.0 Released!"
+    name: "Ben"
+    updated_at: "2012-09-17T16:23:45Z"
+    comments: [
+      {
+        id: 1
+        text: "Woah interesting approach on versioning"
+      }
+    ]
+  },
+  {
+     id: 2
+     title: "Version Cake v0.2.0 Released!"
+     name: "Jim"
+     updated_at: "2012-09-17T16:23:32Z"
+     comments: [
+      {
+        id: 4
+        text: "These new features are greeeeat!"
+      }
+    ]
+  }
+]
+```
+
 ## How to use
 
 ### Configuration
@@ -23,12 +164,12 @@ config.view_versions = [1,3,4,5] # or (1...5)
 ```
 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.
 ```ruby
-config.view_version_extraction_strategy = :http_parameter # [:http_header, :http_accept_parameter, :query_parameter]
+config.view_version_extraction_strategy = :query_parameter # [:http_header, :http_accept_parameter]
 ```
-These are the default strategies:
+These are the available strategies:
+ - **query_parameter**: version in the url query parameter, for testing or to override for special case i.e. ```http://localhost:3000/posts.json?api_version=1```  (This is the default.)
  - **http_header**: Api version HTTP header ie. ```API-Version: 1```
  - **http_accept_parameter**: HTTP Accept header ie. ```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)
- - **query_parameter**: version in the url query parameter, for testing or to override for special case ie. ```http://localhost:3000/posts.json?api_version=1```
  - **custom**: `lambda {|request| request.headers["HTTP_X_API_VERSION"].to_i }` takes the request object and must return an integer
 
 ### Version your views
@@ -52,7 +193,17 @@ If you start supporting a newer version, v3 for instance, you do not have to cop
 ### Controller
 
 You don't need to do anything special in your controller, but if you find that you want to perform some tasks for a specific version you can use `requested_version` and `latest_version`. This may be updated in the [near future](https://github.com/bwillis/versioncake/issues/1).
-
+```ruby
+def index
+  # shared code for all versions
+  @posts = Post.scoped
+
+  # version 3 or greated supports embedding post comments
+  if requested_version >= 3
+    @posts = @posts.includes(:comments)
+  end
+end
+```
 ### Client requests
 
 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``.
@@ -63,11 +214,15 @@ When a client makes a request it will automatically receive the latest supported
 
 - https://github.com/bploetz/versionist
 - https://github.com/filtersquad/rocket_pants
+- https://github.com/lyonrb/biceps
 
 ## Discussions
 
 - [Steve Klabnik on how to version in a resful way](http://blog.steveklabnik.com/posts/2011-07-03-nobody-understands-rest-or-http#i_want_my_api_to_be_versioned)
 - [Rails API project disucssion on versioning](https://github.com/spastorino/rails-api/issues/8)
+- [Railscast on versioning](http://railscasts.com/episodes/350-rest-api-versioning)
+- [Ruby5 on versioncake](http://ruby5.envylabs.com/episodes/310-episode-306-september-18th-2012/stories/2704-version-cake)
+- [Rails core discussion](https://groups.google.com/forum/#!msg/rubyonrails-core/odwmEYYIum0/9POep66BvoMJ)
 
 # Questions?
 

data/lib/versioncake/action_controller/versioning.rb

@@ -4,7 +4,7 @@ module ActionController #:nodoc:
   module Versioning
     extend ActiveSupport::Concern
 
-    attr_accessor :requested_version, :is_latest_version
+    attr_accessor :requested_version, :is_latest_version, :derived_version
 
     included do
       prepend_before_filter :set_version
@@ -12,14 +12,19 @@ module ActionController #:nodoc:
 
     protected
       def set_version
-        requested_version = ActionView::Template::Versions.extract_version request
-        if ActionView::Template::Versions.supports_version? requested_version
-          @requested_version = requested_version
-          @_lookup_context.versions = ActionView::Template::Versions.supported_versions(requested_version)
+        @requested_version = ActionView::Template::Versions.extract_version request
+
+        if @requested_version.nil?
+          @derived_version = ActionView::Template::Versions.latest_version
+        elsif ActionView::Template::Versions.supports_version? requested_version
+          @derived_version = @requested_version
+        elsif requested_version > ActionView::Template::Versions.latest_version
+          raise ActionController::RoutingError.new("No route match for version")
         else
-          @requested_version = ActionView::Template::Versions.latest_version
+          raise ActionController::RoutingError.new("Version is deprecated")
         end
-        @is_latest_version = @requested_version == ActionView::Template::Versions.latest_version
+        @_lookup_context.versions = ActionView::Template::Versions.supported_versions(@derived_version)
+        @is_latest_version = @derived_version == ActionView::Template::Versions.latest_version
       end
   end
 end

data/lib/versioncake/version.rb

@@ -1,3 +1,3 @@
 module VersionCake
-  VERSION = "0.2.0"
+  VERSION = "0.3.0"
 end

data/test/functional/renders_controller_test.rb

@@ -15,7 +15,7 @@ class RendersControllerTest < ActionController::TestCase
   end
 
   test "exposes latest version when requesting the latest" do
-    get :index, "api_version" => "4"
+    get :index, "api_version" => "3"
     assert @controller.is_latest_version
   end
 
@@ -23,6 +23,16 @@ class RendersControllerTest < ActionController::TestCase
     get :index, "api_version" => "1"
     assert !@controller.is_latest_version
   end
+
+  test "exposes the derived version when the version is not set" do
+    get :index
+    assert_equal 3, @controller.derived_version
+  end
+
+  test "requested version is blank when the version is not set" do
+    get :index
+    assert_blank @controller.requested_version
+  end
 end
 
 class ParameterStragegyTest < ActionController::TestCase
@@ -142,4 +152,25 @@ class MultipleStrategyTest < ActionController::TestCase
     get :index, "api_version" => "1"
     assert_equal @response.body, "index.v2.html.erb"
   end
+end
+
+class UnsupportedVersionTest < ActionController::TestCase
+  tests RendersController
+
+  setup do
+    ActionView::Template::Versions.extraction_strategy = :query_parameter
+  end
+
+  test "responds with 404 when the version is larger than the supported version" do
+    assert_raise ActionController::RoutingError do
+      get :index, "api_version" => "4"
+    end
+  end
+
+  test "responds with 404 when the version is lower than the latest version, but not an available version" do
+    ActionView::Template::Versions.supported_version_numbers = [2,3]
+    assert_raise ActionController::RoutingError do
+      get :index, "api_version" => "1"
+    end
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: versioncake
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
   prerelease: 
 platform: ruby
 authors:
@@ -10,7 +10,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-09-16 00:00:00.000000000 Z
+date: 2012-10-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: actionpack
@@ -106,6 +106,7 @@ files:
 - Gemfile.lock
 - README.md
 - Rakefile
+- images/versioncake-logo450x100.png
 - lib/versioncake.rb
 - lib/versioncake/action_controller/versioning.rb
 - lib/versioncake/action_view/lookup_context.rb