api-versions 0.1.0 → 0.2.0

data/.gitignore

@@ -4,3 +4,4 @@ Gemfile.lock
 pkg/*
 spec/dummy/log/*
 log/*
+tmp/*

data/.travis.yml

@@ -6,7 +6,7 @@ rvm:
 branches:
   only:
     - master
-    - develop
+    - production
 
 notifications:
   email:

data/License.txt

@@ -0,0 +1,22 @@
+(The MIT License)
+
+Copyright (c) 2012 Erich Menge
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -1,13 +1,39 @@
-API-Versions [![Build Status](https://secure.travis-ci.org/erichmenge/api-versions.png)](http://travis-ci.org/erichmenge/api-versions)
-======================================================================================================================================
+# api-versions [![Build Status](https://secure.travis-ci.org/erichmenge/api-versions.png)](http://travis-ci.org/erichmenge/api-versions) #
 
-If you have multiple versions of an API in your Rails app, it is not very DRY to include the same resources over and over again.
 
-Also, URL resources shouldn't change. Instead, API versions should be specified in the headers. The api-versions gem provides a nice DSL for this.
+#### api-versions is a Gem to help you manage your Rails API endpoints.
+api-versions is very lightweight. It adds a generator and only one method to the Rails route mapper.
 
+##### It helps you in three ways:
+
+* Provides a DSL for versioning your API in your routes file, favoring client headers vs changing the resource URLs.
+* Provides methods to cache and retrieve resources in your routes file to keep it from getting cluttered
+* Provides a generator to bump your API controllers to the next version, while inheriting the previous version.
+
+*See below for more details on each of these topics*
+
+#### Assumptions api-versions makes:
+* You want the client to use headers to specify the API version instead of changing the URL. (`Accept` header of `application/vnd.myvendor+json;version=1` for example)
+* You specify your API version in whole integers. v1, v2, v3, etc.
+  If you need semantic versioning for an API you're likely making too many backwards incompatible changes. API versions should not change all that often.
+* Your API controllers will live under the `api/v{n}/` directory. For example `app/controllers/api/v1/authorizations_controller.rb`.
+
+## Installation
 In your Gemfile:
 
-    gem "api-versions", "~> 0.1.0"
+    gem "api-versions", "~> 0.2.0"
+
+## Versions are specified by header, not by URL
+A lot of APIs are versioned by changing the URL. `http://test.host/api/v1/some_resource/new` for example.
+But is some_resource different from version 1 to version 2? It is likely the same resource, it is simply the interface that is changing.
+api-versions prefers the URLs stay the same. `http://test.host/api/some_resource/new` need not ever change (so long as the resource exists). The client specifies how it wants to interface with
+this resource with the `Accept` header. So if the client wants version 2 of the API, the `Accept` header might look like this: `application/vnd.myvendor+json;version=2`. A complete example is
+below.
+
+## DSL ##
+api-versions provides a (very) lightweight DSL for your routes file. Everything having to do with your routes API lives in the api block. This DSL helps you version your API as well as providing a caching mechanism to prevent the need of copy/pasting the same resources into new versions of the API.
+
+For example:
 
 In your routes.rb file:
 
@@ -44,7 +70,8 @@ In your routes.rb file:
                             DELETE /api/authorizations/:id(.:format)      api/v2/authorizations#destroy
 
 
-Then the client simply sets the Accept header "application/vnd.myvendor+json;version=1". If no version is specified, the default version you set will be assumed.  You'll of course still need to copy all of your controllers over, even if they haven't changed from version to version.  At least you'll remove a bit of the mess in your routes file.
+Then the client simply sets the Accept header `application/vnd.myvendor+json;version=1`. If no version is specified, the default version you set will be assumed.
+You'll of course still need to copy all of your controllers over, even if they haven't changed from version to version.  At least you'll remove a bit of the mess in your routes file.
 
 A more complicated example:
 
@@ -133,13 +160,28 @@ And finally `rake routes` outputs:
                               GET    /api/my_new_resource/:id(.:format)      api/v3/my_new_resource#show
                               PUT    /api/my_new_resource/:id(.:format)      api/v3/my_new_resource#update
                               DELETE /api/my_new_resource/:id(.:format)      api/v3/my_new_resource#destroy
+## api_versions:bump
+The api-versions gem provides a Rails generator called `api_versions:bump`. This generator will go through all of your API controllers and find the highest version number and bump
+all controllers with it up to the next in sequence.
 
-License
-=======
-Copyright (c) 2012 Erich Menge
+If for example you have a controller `api/v1/authorizations_controller.rb` it will create `api/v2/authorizations_controller.rb` and inside:
 
-Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+``` ruby
+class Api::V2::AuthorizationsController < Api::V1::AuthorizationsController
+end
+```
+
+So instead of copying your prior version controllers over to the new ones and duplicating all the code in them, you can redefine specific methods,
+or start from scratch by removing the inheritance.
 
-The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+## A word on Rails responders
+If you use `responds_to` and `responds_with` you'll run into a bit of a problem. Rails doesn't understand the Accept header so you'll get a 406 Unacceptable when you use `respond_to`.
+To get around this I suggest creating a base API controller and including ApiVersions::SimplifyFormat, which will set the format to the one specified with the + symbol in the Accept header.
+
+``` ruby
+class Api::V1::BaseController < ActionController::Base
+  include ApiVersions::SimplifyFormat
+end
+```
 
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+This will set `request.format` accordingly.

data/api-versions.gemspec

@@ -8,8 +8,8 @@ Gem::Specification.new do |s|
   s.authors     = ["Erich Menge"]
   s.email       = ["erich.menge@me.com"]
   s.homepage    = "https://github.com/erichmenge/api-versions"
-  s.summary     = "Allows you to cache routing and then inherit it in other modules."
-  s.description = "Useful for API versioning."
+  s.summary     = "An API versioning gem for Rails."
+  s.description = "api-versions helps manage your app's API endpoints."
 
   s.rubyforge_project = "api-versions"
 
@@ -18,5 +18,6 @@ Gem::Specification.new do |s|
   s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
   s.require_paths = ["lib"]
 
-  s.add_development_dependency "rspec-rails"
+  s.add_development_dependency "rspec-rails", "~> 2.0"
+  s.add_development_dependency 'ammeter',  '0.2.5'
 end

data/lib/api-versions.rb

@@ -1,6 +1,8 @@
 require "api-versions/version"
 require "api-versions/version_check"
 require "api-versions/dsl"
+require "api-versions/simplify_format"
+
 
 module ApiVersions
   def api(options = {}, &block)

data/lib/api-versions/dsl.rb

@@ -17,7 +17,7 @@ module ApiVersions
     end
 
     def inherit(args)
-      [*args[:from]].each do |block|
+      Array.wrap(args[:from]).each do |block|
          @resource_cache[block].call
       end
     end

data/lib/api-versions/simplify_format.rb

@@ -0,0 +1,15 @@
+module ApiVersions
+  module SimplifyFormat
+    extend ActiveSupport::Concern
+
+    included do
+      before_filter :simplify_format
+    end
+
+    private
+
+    def simplify_format
+      request.headers['Accept'] && request.headers['Accept'].match(/\+\s*(.+?)[;\s\z]/) { |m| request.format = m[1] }
+    end
+  end
+end

data/lib/api-versions/version.rb

@@ -1,3 +1,3 @@
 module ApiVersions
-    VERSION = "0.1.0"
+    VERSION = "0.2.0"
 end

data/lib/api-versions/version_check.rb

@@ -13,15 +13,15 @@ module ApiVersions
     private
 
     def accepts_proper_format?(request)
-      !!(request.headers['Accept'] =~ /^application\/vnd\.#{self.class.vendor_string}\+.+/)
+      request.headers['Accept'] =~ /\Aapplication\/vnd\.#{self.class.vendor_string}\+.+/
     end
 
     def matches_version?(request)
-      !!(request.headers['Accept'] =~ /version\s*?=\s*?#{@process_version}\b/)
+      request.headers['Accept'] =~ /version\s*?=\s*?#{@process_version}\b/
     end
 
     def unversioned?(request)
-        @process_version == self.class.default_version && !(request.headers['Accept'] =~ /version\s*?=\s*?\d*\b/i)
+      @process_version == self.class.default_version && !(request.headers['Accept'] =~ /version\s*?=\s*?\d*\b/i)
     end
   end
 end

data/lib/generators/api_versions/bump_generator.rb

@@ -0,0 +1,29 @@
+module ApiVersions
+  module Generators
+    class BumpGenerator < Rails::Generators::Base
+      desc "Bump API version to next version, initializing controllers"
+      source_root File.expand_path('../templates', __FILE__)
+
+      def get_controllers
+        Dir.chdir File.join(Rails.root, 'app', 'controllers') do
+          @controllers = Dir.glob('api/v**/**/*.rb')
+        end
+
+        @highest_version = @controllers.map do |controller|
+          controller.match(/api\/v(\d+?)\//)[1]
+        end.max
+
+        @controllers.keep_if { |element| element =~ /api\/v#{@highest_version}\// }
+      end
+
+      def generate_new_controllers
+        @controllers.each do |controller|
+          new_controller = controller.gsub /api\/v#{@highest_version}\//, "api/v#{@highest_version.to_i + 1}/"
+          @current_new_controller = new_controller.chomp(File.extname(controller)).camelize
+          @current_old_controller = controller.chomp(File.extname(controller)).camelize
+          template 'controller.rb', File.join('app', 'controllers', new_controller)
+        end
+      end
+    end
+  end
+end

data/lib/generators/api_versions/templates/controller.rb

@@ -0,0 +1,2 @@
+class <%= @current_new_controller %> < <%= @current_old_controller %>
+end

data/spec/controllers/application_controller_spec.rb

@@ -0,0 +1,31 @@
+require 'spec_helper'
+
+class ApplicationController < ActionController::Base
+  include ApiVersions::SimplifyFormat
+
+  def index
+    render nothing: true, status: 200
+  end
+end
+
+describe ApplicationController do
+  describe "simplify format" do
+    it "should set the format" do
+      request.env['Accept'] = 'application/vnd.myvendor+json;version=1'
+      get :index
+      request.format.should == 'application/json'
+    end
+  end
+
+  context "when the header is not set" do
+    it "should be successful" do
+      get :index
+      response.should be_success
+    end
+
+    it "should not change the format" do
+      get :index
+      request.format.should == "text/html"
+    end
+  end
+end

data/spec/dummy/app/controllers/api/v2/users_controller.rb

@@ -0,0 +1,2 @@
+class Api::V2::UsersController < ApplicationController
+end

data/spec/dummy/app/controllers/api/v3/foo_controller.rb

@@ -0,0 +1,2 @@
+class Api::V3::FooController < ApplicationController
+end

data/spec/dummy/app/controllers/api/v3/nests/nested_controller.rb

@@ -0,0 +1,2 @@
+class Api::V3::Nests::NestedController
+end

data/spec/dummy/config/routes.rb

@@ -17,4 +17,6 @@ Dummy::Application.routes.draw do
       inherit from: 'v2'
     end
   end
+
+  match '/app/index' => 'application#index'
 end

data/spec/generators/bump_generator_spec.rb

@@ -0,0 +1,40 @@
+require 'spec_helper'
+require 'generators/api_versions/bump_generator'
+
+describe ApiVersions::Generators::BumpGenerator do
+  before do
+    destination File.expand_path("../../../tmp", __FILE__)
+    prepare_destination
+  end
+
+  describe "Generated files" do
+    before { run_generator }
+
+    describe "Bar Controller" do
+      subject { file('app/controllers/api/v4/bar_controller.rb') }
+
+      it { should exist }
+      it { should contain /Api::V4::BarController < Api::V3::BarController/ }
+    end
+
+    describe "Foo Controller" do
+      subject { file('app/controllers/api/v4/foo_controller.rb') }
+
+      it { should exist }
+      it { should contain /Api::V4::FooController < Api::V3::FooController/ }
+    end
+
+    describe "Nested Controller" do
+      subject { file('app/controllers/api/v4/nests/nested_controller.rb') }
+
+      it { should exist }
+      it { should contain /Api::V4::Nests::NestedController < Api::V3::Nests::NestedController/ }
+    end
+
+    describe "Users Controller" do
+      subject { file('app/controllers/api/v4/users_controller.rb') }
+
+      it { should_not exist }
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -3,6 +3,7 @@ ENV["RAILS_ENV"] ||= 'test'
 require File.expand_path("../dummy/config/environment", __FILE__)
 require 'rspec/rails'
 require 'rspec/autorun'
+require 'ammeter/init'
 
 # Requires supporting ruby files with custom matchers and macros, etc,
 # in spec/support/ and its subdirectories.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: api-versions
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,25 +9,41 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-08-30 00:00:00.000000000 Z
+date: 2012-09-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec-rails
   requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
-    - - ! '>='
+    - - ~>
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '2.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     none: false
     requirements:
-    - - ! '>='
+    - - ~>
       - !ruby/object:Gem::Version
-        version: '0'
-description: Useful for API versioning.
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: ammeter
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.2.5
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.2.5
+description: api-versions helps manage your app's API endpoints.
 email:
 - erich.menge@me.com
 executables: []
@@ -37,17 +53,25 @@ files:
 - .gitignore
 - .travis.yml
 - Gemfile
+- License.txt
 - README.md
 - Rakefile
 - api-versions.gemspec
 - lib/api-versions.rb
 - lib/api-versions/dsl.rb
+- lib/api-versions/simplify_format.rb
 - lib/api-versions/version.rb
 - lib/api-versions/version_check.rb
+- lib/generators/api_versions/bump_generator.rb
+- lib/generators/api_versions/templates/controller.rb
+- spec/controllers/application_controller_spec.rb
 - spec/dummy/app/controllers/api/v1/bar_controller.rb
 - spec/dummy/app/controllers/api/v2/bar_controller.rb
 - spec/dummy/app/controllers/api/v2/foo_controller.rb
+- spec/dummy/app/controllers/api/v2/users_controller.rb
 - spec/dummy/app/controllers/api/v3/bar_controller.rb
+- spec/dummy/app/controllers/api/v3/foo_controller.rb
+- spec/dummy/app/controllers/api/v3/nests/nested_controller.rb
 - spec/dummy/app/controllers/application_controller.rb
 - spec/dummy/config.ru
 - spec/dummy/config/application.rb
@@ -56,6 +80,7 @@ files:
 - spec/dummy/config/environments/test.rb
 - spec/dummy/config/routes.rb
 - spec/dummy/log/.gitkeep
+- spec/generators/bump_generator_spec.rb
 - spec/routing/routing_spec.rb
 - spec/spec_helper.rb
 homepage: https://github.com/erichmenge/api-versions
@@ -78,15 +103,19 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: api-versions
-rubygems_version: 1.8.24
+rubygems_version: 1.8.23
 signing_key: 
 specification_version: 3
-summary: Allows you to cache routing and then inherit it in other modules.
+summary: An API versioning gem for Rails.
 test_files:
+- spec/controllers/application_controller_spec.rb
 - spec/dummy/app/controllers/api/v1/bar_controller.rb
 - spec/dummy/app/controllers/api/v2/bar_controller.rb
 - spec/dummy/app/controllers/api/v2/foo_controller.rb
+- spec/dummy/app/controllers/api/v2/users_controller.rb
 - spec/dummy/app/controllers/api/v3/bar_controller.rb
+- spec/dummy/app/controllers/api/v3/foo_controller.rb
+- spec/dummy/app/controllers/api/v3/nests/nested_controller.rb
 - spec/dummy/app/controllers/application_controller.rb
 - spec/dummy/config.ru
 - spec/dummy/config/application.rb
@@ -95,5 +124,6 @@ test_files:
 - spec/dummy/config/environments/test.rb
 - spec/dummy/config/routes.rb
 - spec/dummy/log/.gitkeep
+- spec/generators/bump_generator_spec.rb
 - spec/routing/routing_spec.rb
 - spec/spec_helper.rb