versionable_api 0.0.2 → 0.0.3

data/README.md

@@ -6,13 +6,13 @@ VersionableApi is a small gem that helps you create versionable apis (initially
 
 The most common way to start trying to version APIs is to create URIs (and routes and controllers) that look somewhat like this:
 ```
-/api/v1/person.json
+/api/v1/people.json
 ```
 and route that to a controller in `app/controllers/api/v1/people_controller.rb`
 
 Then, when you want to make a change to the person API, you create:
 ```
-/api/v2/person.json
+/api/v2/people.json
 ```
 and you create `app/controllers/api/v2/people_controller.rb`.
 
@@ -20,20 +20,20 @@ But do you make `Api::V2::PeopleController` inherit from `Api::V1::PeopleControl
 
 # How VersionableApi tries to solve this problem
 
-`VersionableApi` proposes that you create tiny controllers and then put version-specific behavior in modules that are included in that controller.  `VersionableApi` provides a module that does a tiny bit of magic to determine which "versioned" method gets called based on an HTTP Accept header and will look for lower versions of the methods in case a particular method on a controller hasn't revved yet.
+`VersionableApi` proposes that you create tiny controllers and then put version-specific behavior in modules that are included in that controller.  `VersionableApi` provides a module that does a tiny bit of magic to determine which "versioned" method gets called based on an HTTP Accept header.
 
 Instead of putting the version of the API you want to call in the request URI, it's specified in the Accept Header by adding `;version=X` to one of the acceptable types.  The easiest way is to specify an accept type of `*/*;version=X` (where X is the version you want).
 
 # Maintaining backwards compatibility with clients who are already using the "old" URI style
 
-If you're transitioning an existing API to using VersionableApi and you need to be able to handle 'old' style routes (like `/api/v2/something.json`) VersionableApi provides a simple piece of Rack middleware that can help.
+If you're transitioning an existing API to using VersionableApi and you need to be able to handle 'old' style routes (like `/api/v2/something.json`) `VersionableApi` provides a simple piece of Rack middleware that can help.
 
 The `VersionableApi::ApiVersionInterceptor` can intercept requests to the 'old' api style and massage them to fit your new style.  You can include it by adding the following line inside your `config/application.rb` class:
 ```
 config.middleware.use "VersionableApi::ApiVersionInterceptor"
 ```
 
-By default, it will look for requests to paths that look like `/api/v#/something` and transform them into `/api/something` with `*/*;version=#` prepended to the HTTP_ACCEPT header and then forward the request on to your Rails app. You can configure most of how it behaves via initialization parameters if you don't like the defaults, for example:
+By default, it will look for requests to paths that look like `/api/v#/something` and transform them into `/api/something` with `*/*;version=#` prepended to the `HTTP_ACCEPT` header and then forward the request on to your Rails app. You can configure most of how it behaves via initialization parameters if you don't like the defaults, for example:
 ```
 config.middleware.use "VersionableApi::ApiVersionInterceptor", {version_regex: /\/API\/version-(?<version>\d+)\/(?<path>.*)/}
 ```
@@ -87,7 +87,7 @@ the `Api::V1::People#show_v1` method will handle the request.
 ```
 GET /api/people.json {HTTP_ACCEPT: text/json;version=2}
 ```
-the request will get handled by the `Api::V1::People#index_v1` action.  Even though the request specified that it's using Version 2, since there isn't an explicit Version 2 of the `index` action, control will fall back to the Version 1 version.
+a 404 will be returned because there is no version 2 of the `index` action.
 
 
 # How to use it

data/lib/versionable_api/api_versioning.rb

@@ -1,14 +1,16 @@
 module VersionableApi
   module ApiVersioning
 
-    # Public: The default version, classes including ApiVersioning should specify
-    # this themselves if they don't want the default version to be 1
+    # Public: The default version. Classes including ApiVersioning should specify
+    # this themselves if they don't want the default version to be 1.  If you would
+    # like to force the caller to specify a version in their request, override
+    # this method have have it return nil.
     #
     # Returns the duplicated String.
     def default_version
       1
     end
-        
+
     # Public: Returns a versioned action name based on the requested action name
     # and an optional version specification on the request.  If no versioned
     # action matching what we think the request is trying to access is defined on
@@ -22,18 +24,18 @@ module VersionableApi
     #
     # Returns a versioned action name, "_handle_action_missing", or nil
     def method_for_action(action)
-      version = (requested_version || self.default_version || 1).to_i
-      method = nil
-      version.downto(1) do |v|
-        name = "#{action}_v#{v}"
-        method ||= self.respond_to?(name) ? name : nil
+      version = (requested_version || self.default_version)
+
+      unless version.nil?
+        version = version.to_i
+        name = "#{action}_v#{version}"
+        method = self.respond_to?(name) ? name : nil
       end
 
       method ||= self.respond_to?("action_missing") ? "_handle_action_missing" : nil
-
     end
 
-    
+
     # Public: Finds the API version requested in the request
     #
     # Returns the requested version, or nil if no version was specifically requested

data/lib/versionable_api/version.rb

@@ -1,3 +1,3 @@
 module VersionableApi
-  VERSION = "0.0.2"
+  VERSION = "0.0.3"
 end

data/test/spec/versionable_api_test.rb

@@ -2,7 +2,7 @@ require 'test_helper'
 require 'ostruct'
 
 describe VersionableApi::ApiVersioning do
-  class Testable 
+  class Testable
     include VersionableApi::ApiVersioning
     attr_accessor :request
     def initialize
@@ -11,62 +11,75 @@ describe VersionableApi::ApiVersioning do
     end
   end
 
-  before do 
+  class TestableRequireVersion < Testable
+    def default_version
+      nil
+    end
+  end
+
+  before do
     @test_me = Testable.new
   end
 
-  it "should have a default version of 1" do 
-    assert_equal 1, @test_me.default_version
+  describe "default version" do
+    it "should have a default version of 1" do
+      assert_equal 1, @test_me.default_version
+    end
+    it "should require a version from the client if default version is nil" do
+      @test_me = TestableRequireVersion.new
+      assert_nil @test_me.default_version
+      assert_nil @test_me.method_for_action("show")
+    end
   end
 
-  describe "#requested_version" do 
-    it "should determine the requested version from the request headers" do 
+  describe "#requested_version" do
+    it "should determine the requested version from the request headers" do
       @test_me.request.headers["HTTP_ACCEPT"] = "*/*;version=10"
       assert_equal 10, @test_me.requested_version
     end
 
-    it "should return nil if no explicit version is requested" do 
+    it "should return nil if no explicit version is requested" do
       assert_nil @test_me.requested_version
     end
 
-    it "should return nil if the version requested is non-numeric" do 
+    it "should return nil if the version requested is non-numeric" do
       @test_me.request.headers["HTTP_ACCEPT"] = "*/*;version=FOO"
       assert_nil @test_me.requested_version
     end
   end
 
-  describe "#method_for_action" do 
-    before do 
+  describe "#method_for_action" do
+    before do
       def @test_me.show_v1; 1; end;
       def @test_me.show_v2; 2; end;
       def @test_me.index_v1; 1; end;
     end
 
-    it "should return the default version when no version is requested" do 
+    it "should return the default version when no version is requested" do
       assert_equal "show_v1", @test_me.method_for_action("show")
     end
 
-    it "should return the requested version if specified and available" do 
+    it "should return the requested version if specified and available" do
       @test_me.request.headers["HTTP_ACCEPT"] = "*/*;version=2"
       assert_equal "show_v2", @test_me.method_for_action("show")
       @test_me.request.headers["HTTP_ACCEPT"] = "*/*;version=1"
       assert_equal "show_v1", @test_me.method_for_action("show")
     end
 
-    it "should return the highest available version if the version specified is higher than the available versions" do 
+    it "should return nil if the version specified is higher than the available versions" do
       @test_me.request.headers["HTTP_ACCEPT"] = "*/*;version=10"
-      assert_equal "show_v2", @test_me.method_for_action("show")
+      assert_nil @test_me.method_for_action("show")
       @test_me.request.headers["HTTP_ACCEPT"] = "*/*;version=2"
-      assert_equal "index_v1", @test_me.method_for_action("index")
+      assert_nil @test_me.method_for_action("index")
     end
 
-    it "should return _handle_action_missing if #action_missing is defined and unkown action is called for" do 
+    it "should return _handle_action_missing if #action_missing is defined and unkown action is called for" do
       def @test_me.action_missing; true; end;
       @test_me.request.headers["HTTP_ACCEPT"] = "*/*;version=2"
       assert_equal "_handle_action_missing", @test_me.method_for_action("foobar")
     end
 
-    it "should return nil if #action_missing is not defined and an unkown action is specified" do 
+    it "should return nil if #action_missing is not defined and an unkown action is specified" do
       @test_me.request.headers["HTTP_ACCEPT"] = "*/*;version=2"
       assert_nil @test_me.method_for_action("foobar")
     end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: versionable_api
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.0.3
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-08-29 00:00:00.000000000 Z
+date: 2013-11-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
@@ -57,12 +57,18 @@ required_ruby_version: !ruby/object:Gem::Requirement
   - - ! '>='
     - !ruby/object:Gem::Version
       version: '0'
+      segments:
+      - 0
+      hash: -1992996191972482845
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
   - - ! '>='
     - !ruby/object:Gem::Version
       version: '0'
+      segments:
+      - 0
+      hash: -1992996191972482845
 requirements: []
 rubyforge_project: 
 rubygems_version: 1.8.23