api-versions 0.0.5 → 0.1.0

data/.gitignore

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

data/README.md

@@ -2,88 +2,137 @@ API-Versions [![Build Status](https://secure.travis-ci.org/erichmenge/api-versio
 ======================================================================================================================================
 
 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.
+
 In your Gemfile:
 
-	gem "api-versions", "~> 0.0.4"
+    gem "api-versions", "~> 0.1.0"
 
 In your routes.rb file:
 
-	namespace :api do
-	  default_api_version 	1   			 # If no API version is specified in the Accept header, this is what will be used.
-	  api_vendor 			"myvendor"   	 # For HTTP Accept Header application/vnd.myvendor+json;version=1
-
-	   constraints api_version_check(:version => 1) do
-	     scope :module => :v1 do
-	       cache_resources :as => :v1 do
-	         resources :authorizations
-	       end
-	     end
-	  end
-
-	  constraints api_version_check(:version => 2) do
-	     scope :module => :v2 do
-	       inherit_resources :from => :v1
-	     end
-	  end
-	end
-
-rake routes outputs:
-
-	    api_authorizations GET    /api/authorizations(.:format)          api/v1/authorizations#index
-	                       POST   /api/authorizations(.:format)          api/v1/authorizations#create
-	 new_api_authorization GET    /api/authorizations/new(.:format)      api/v1/authorizations#new
-	edit_api_authorization GET    /api/authorizations/:id/edit(.:format) api/v1/authorizations#edit
-	     api_authorization GET    /api/authorizations/:id(.:format)      api/v1/authorizations#show
-	                       PUT    /api/authorizations/:id(.:format)      api/v1/authorizations#update
-	                       DELETE /api/authorizations/:id(.:format)      api/v1/authorizations#destroy
-	                       GET    /api/authorizations(.:format)          api/v2/authorizations#index
-	                       POST   /api/authorizations(.:format)          api/v2/authorizations#create
-	                       GET    /api/authorizations/new(.:format)      api/v2/authorizations#new
-	                       GET    /api/authorizations/:id/edit(.:format) api/v2/authorizations#edit
-	                       GET    /api/authorizations/:id(.:format)      api/v2/authorizations#show
-	                       PUT    /api/authorizations/:id(.:format)      api/v2/authorizations#update
-	                       DELETE /api/authorizations/:id(.:format)      api/v2/authorizations#destroy
+``` ruby
+  # You can leave default_version out, but if you do the first version used will become the default
+  api vendor_string: "myvendor", default_version: 1 do
+    version 1 do
+      cache as: 'v1' do
+        resources :authorizations
+      end
+    end
+
+    version 2 do
+      inherit from: 'v1'
+    end
+  end
+```
+
+`rake routes` outputs:
+
+    api_authorizations      GET    /api/authorizations(.:format)          api/v1/authorizations#index
+                            POST   /api/authorizations(.:format)          api/v1/authorizations#create
+    new_api_authorization   GET    /api/authorizations/new(.:format)      api/v1/authorizations#new
+    edit_api_authorization  GET    /api/authorizations/:id/edit(.:format) api/v1/authorizations#edit
+     api_authorization      GET    /api/authorizations/:id(.:format)      api/v1/authorizations#show
+                            PUT    /api/authorizations/:id(.:format)      api/v1/authorizations#update
+                            DELETE /api/authorizations/:id(.:format)      api/v1/authorizations#destroy
+                            GET    /api/authorizations(.:format)          api/v2/authorizations#index
+                            POST   /api/authorizations(.:format)          api/v2/authorizations#create
+                            GET    /api/authorizations/new(.:format)      api/v2/authorizations#new
+                            GET    /api/authorizations/:id/edit(.:format) api/v2/authorizations#edit
+                            GET    /api/authorizations/:id(.:format)      api/v2/authorizations#show
+                            PUT    /api/authorizations/:id(.:format)      api/v2/authorizations#update
+                            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.
 
-A more complicated example
---------------------------
-	namespace :api do
-	  default_api_version 	1
-	  api_vendor 		 	"myvendor"
-
-	  constraints api_version_check(:version => 1) do
-	     scope :module => :v1 do
-	       cache_resources :as => :v1 do
-	        resources :authorizations, :only => [ :create ]
-	        resources :foo
-	        resources :bar
-	      end
-	     end
-	  end
-
-	# Version 2 of the API has everything in Version 1, plus my_new_resource
-	# Version 2 will cache this entire package of resources
-	  constraints api_version_check(:version => 2) do
-	     scope :module => :v2 do
-	       cache_resources :as => :v2 do
-	         resources :my_new_resource
-	         inherit_resources :from => :v1
-	      end
-	     end
-	  end
-
-	# Version 3 of the API has everything in API Version 2, and by
-	# virtue of API Version 2 having everything in Version 1, Version 3
-	# also has everything in Version 1.
-
-	  constraints api_version_check(:version => 3) do
-	     scope :module => :v3 do
-	        inherit_resources :from => :v2
-	     end
-	  end
-
-	end
+A more complicated example:
+
+``` ruby
+  api vendor_string: "myvendor", default_version: 1 do
+    version 1 do
+      cache as: 'v1' do
+        resources :authorizations, only: :create
+        resources :foo
+        resources :bar
+      end
+    end
+
+    version 2 do
+      cache as: 'v2' do
+        inherit from: 'v1'
+        resources :my_new_resource
+      end
+    end
+
+    # V3 has everything in V2, and everything in V1 as well by virtue of V1 being cached in V2.
+    version 3 do
+      inherit from: 'v2'
+    end
+  end
+```
+
+And finally `rake routes` outputs:
+
+    api_authorizations        POST   /api/authorizations(.:format)           api/v1/authorizations#create
+                api_foo_index GET    /api/foo(.:format)                      api/v1/foo#index
+                              POST   /api/foo(.:format)                      api/v1/foo#create
+                  new_api_foo GET    /api/foo/new(.:format)                  api/v1/foo#new
+                 edit_api_foo GET    /api/foo/:id/edit(.:format)             api/v1/foo#edit
+                      api_foo GET    /api/foo/:id(.:format)                  api/v1/foo#show
+                              PUT    /api/foo/:id(.:format)                  api/v1/foo#update
+                              DELETE /api/foo/:id(.:format)                  api/v1/foo#destroy
+                api_bar_index GET    /api/bar(.:format)                      api/v1/bar#index
+                              POST   /api/bar(.:format)                      api/v1/bar#create
+                  new_api_bar GET    /api/bar/new(.:format)                  api/v1/bar#new
+                 edit_api_bar GET    /api/bar/:id/edit(.:format)             api/v1/bar#edit
+                      api_bar GET    /api/bar/:id(.:format)                  api/v1/bar#show
+                              PUT    /api/bar/:id(.:format)                  api/v1/bar#update
+                              DELETE /api/bar/:id(.:format)                  api/v1/bar#destroy
+                              POST   /api/authorizations(.:format)           api/v2/authorizations#create
+                              GET    /api/foo(.:format)                      api/v2/foo#index
+                              POST   /api/foo(.:format)                      api/v2/foo#create
+                              GET    /api/foo/new(.:format)                  api/v2/foo#new
+                              GET    /api/foo/:id/edit(.:format)             api/v2/foo#edit
+                              GET    /api/foo/:id(.:format)                  api/v2/foo#show
+                              PUT    /api/foo/:id(.:format)                  api/v2/foo#update
+                              DELETE /api/foo/:id(.:format)                  api/v2/foo#destroy
+                              GET    /api/bar(.:format)                      api/v2/bar#index
+                              POST   /api/bar(.:format)                      api/v2/bar#create
+                              GET    /api/bar/new(.:format)                  api/v2/bar#new
+                              GET    /api/bar/:id/edit(.:format)             api/v2/bar#edit
+                              GET    /api/bar/:id(.:format)                  api/v2/bar#show
+                              PUT    /api/bar/:id(.:format)                  api/v2/bar#update
+                              DELETE /api/bar/:id(.:format)                  api/v2/bar#destroy
+    api_my_new_resource_index GET    /api/my_new_resource(.:format)          api/v2/my_new_resource#index
+                              POST   /api/my_new_resource(.:format)          api/v2/my_new_resource#create
+      new_api_my_new_resource GET    /api/my_new_resource/new(.:format)      api/v2/my_new_resource#new
+     edit_api_my_new_resource GET    /api/my_new_resource/:id/edit(.:format) api/v2/my_new_resource#edit
+          api_my_new_resource GET    /api/my_new_resource/:id(.:format)      api/v2/my_new_resource#show
+                              PUT    /api/my_new_resource/:id(.:format)      api/v2/my_new_resource#update
+                              DELETE /api/my_new_resource/:id(.:format)      api/v2/my_new_resource#destroy
+                              POST   /api/authorizations(.:format)           api/v3/authorizations#create
+                              GET    /api/foo(.:format)                      api/v3/foo#index
+                              POST   /api/foo(.:format)                      api/v3/foo#create
+                              GET    /api/foo/new(.:format)                  api/v3/foo#new
+                              GET    /api/foo/:id/edit(.:format)             api/v3/foo#edit
+                              GET    /api/foo/:id(.:format)                  api/v3/foo#show
+                              PUT    /api/foo/:id(.:format)                  api/v3/foo#update
+                              DELETE /api/foo/:id(.:format)                  api/v3/foo#destroy
+                              GET    /api/bar(.:format)                      api/v3/bar#index
+                              POST   /api/bar(.:format)                      api/v3/bar#create
+                              GET    /api/bar/new(.:format)                  api/v3/bar#new
+                              GET    /api/bar/:id/edit(.:format)             api/v3/bar#edit
+                              GET    /api/bar/:id(.:format)                  api/v3/bar#show
+                              PUT    /api/bar/:id(.:format)                  api/v3/bar#update
+                              DELETE /api/bar/:id(.:format)                  api/v3/bar#destroy
+                              GET    /api/my_new_resource(.:format)          api/v3/my_new_resource#index
+                              POST   /api/my_new_resource(.:format)          api/v3/my_new_resource#create
+                              GET    /api/my_new_resource/new(.:format)      api/v3/my_new_resource#new
+                              GET    /api/my_new_resource/:id/edit(.:format) api/v3/my_new_resource#edit
+                              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
 
 License
 =======

data/api-versions.gemspec

@@ -4,7 +4,7 @@ require "api-versions/version"
 
 Gem::Specification.new do |s|
   s.name        = "api-versions"
-  s.version     = Api::Versions::VERSION
+  s.version     = ApiVersions::VERSION
   s.authors     = ["Erich Menge"]
   s.email       = ["erich.menge@me.com"]
   s.homepage    = "https://github.com/erichmenge/api-versions"

data/lib/api-versions.rb

@@ -1,58 +1,15 @@
 require "api-versions/version"
+require "api-versions/version_check"
+require "api-versions/dsl"
 
 module ApiVersions
-  def inherit_resources(args)
-    [*args[:from]].each do |block|
-      @resource_cache[block].call
-    end
-  end
-
-  def cache_resources(args, &block)
-    @resource_cache ||= {}
-    @resource_cache.merge!(args[:as] => block)
-    block.call
-  end
-
-  def api_version=(version)
-    ApiVersions::ApiVersionCheck.api_version = version
-  end
-  alias_method :default_api_version, :api_version=
-
-
-  def vendor=(vendor)
-    ApiVersions::ApiVersionCheck.api_vendor = vendor
-  end
-  alias_method :api_vendor, :vendor=
-
-  def api_version_check(*args)
-    ApiVersions::ApiVersionCheck.new(*args)
-  end
-
-  class ApiVersionCheck
-
-    cattr_accessor :api_version, :api_vendor
-
-    def initialize(args = {})
-      @process_version = args[:version]
-    end
-
-    def matches?(request)
-      accepts_proper_format?(request) && (matches_version?(request) || unversioned?(request))
-    end
-
-    private
-
-    def accepts_proper_format?(request)
-      !!(request.headers['Accept'] =~ /^application\/vnd\.#{self.class.api_vendor}\+.+/)
-    end
+  def api(options = {}, &block)
+    VersionCheck.default_version = options[:default_version]
+    VersionCheck.vendor_string   = options[:vendor_string]
 
-    def matches_version?(request)
-      !!(request.headers['Accept'] =~ /version\s*?=\s*?#{@process_version}\b/)
-    end
+    raise "Please set a vendor_string for the api method" if options[:vendor_string].nil?
 
-    def unversioned?(request)
-        @process_version == self.class.api_version && !(request.headers['Accept'] =~ /version\s*?=\s*?\d*\b/i)
-    end
+    namespace(:api) { DSL.new(self, &block) }
   end
 end
 

data/lib/api-versions/dsl.rb

@@ -0,0 +1,31 @@
+module ApiVersions
+  class DSL
+    extend Forwardable
+
+    def initialize(context, &block)
+      @context = context
+      self.class.def_delegators :@context, *(@context.public_methods - public_methods)
+      instance_eval &block
+    end
+
+    def version(version_number, &block)
+      VersionCheck.default_version ||= version_number
+
+      constraints VersionCheck.new(version: version_number) do
+        scope({ module: "v#{version_number}" }, &block)
+      end
+    end
+
+    def inherit(args)
+      [*args[:from]].each do |block|
+         @resource_cache[block].call
+      end
+    end
+
+    def cache(args, &block)
+      @resource_cache ||= {}
+      @resource_cache[args[:as]] = block
+      block.call
+    end
+  end
+end

data/lib/api-versions/version.rb

@@ -1,5 +1,3 @@
-module Api
-  module Versions
-    VERSION = "0.0.5"
-  end
+module ApiVersions
+    VERSION = "0.1.0"
 end

data/lib/api-versions/version_check.rb

@@ -0,0 +1,27 @@
+module ApiVersions
+  class VersionCheck
+    cattr_accessor :default_version, :vendor_string
+
+    def initialize(args = {})
+      @process_version = args[:version]
+    end
+
+    def matches?(request)
+      accepts_proper_format?(request) && (matches_version?(request) || unversioned?(request))
+    end
+
+    private
+
+    def accepts_proper_format?(request)
+      !!(request.headers['Accept'] =~ /^application\/vnd\.#{self.class.vendor_string}\+.+/)
+    end
+
+    def matches_version?(request)
+      !!(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)
+    end
+  end
+end

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

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

data/spec/dummy/config/routes.rb

@@ -1,25 +1,20 @@
 Dummy::Application.routes.draw do
-  namespace :api do
-    default_api_version   1
-    api_vendor            "myvendor"
+  api vendor_string: "myvendor" do
+    version 1 do
+      cache as: 'v1' do
+        resources :bar
+      end
+    end
 
-    constraints api_version_check(:version => 1) do
-       scope :module => :v1 do
-         cache_resources :as => :v1 do
-          resources :bar
-        end
-       end
+    version 2 do
+      cache as: 'v2' do
+        resources :foo
+        inherit from: 'v1'
+      end
     end
 
-  # Version 2 of the API has everything in Version 1, plus my_new_resource
-  # Version 2 will cache this entire package of resources
-    constraints api_version_check(:version => 2) do
-       scope :module => :v2 do
-         cache_resources :as => :v2 do
-           resources :foo
-           inherit_resources :from => :v1
-        end
-       end
+    version 3 do
+      inherit from: 'v2'
     end
   end
 end

data/spec/routing/routing_spec.rb

@@ -60,11 +60,18 @@ describe 'API Routing' do
     end
 
     it "should default" do
-      original_version = ApiVersions::ApiVersionCheck.api_version
-      ApiVersions::ApiVersionCheck.api_version = 2
+      original_version = ApiVersions::VersionCheck.default_version
+      ApiVersions::VersionCheck.default_version = 2
       merge_and_stub new_api_foo_path, 'get', 'Accept' => 'application/vnd.myvendor+json'
       expect(get: new_api_foo_path).to route_to(controller: 'api/v2/foo', action: 'new')
-      ApiVersions::ApiVersionCheck.api_version = original_version
+      ApiVersions::VersionCheck.default_version = original_version
+    end
+  end
+
+  describe "V3" do
+    it "should copy foo" do
+      merge_and_stub new_api_bar_path, 'get', 'Accept' => 'application/vnd.myvendor+json;version=3'
+      expect(get: new_api_bar_path).to route_to(controller: 'api/v3/bar', action: 'new')
     end
   end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: api-versions
 version: !ruby/object:Gem::Version
-  version: 0.0.5
+  version: 0.1.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-08-28 00:00:00.000000000 Z
+date: 2012-08-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec-rails
@@ -41,11 +41,13 @@ files:
 - Rakefile
 - api-versions.gemspec
 - lib/api-versions.rb
+- lib/api-versions/dsl.rb
 - lib/api-versions/version.rb
-- spec/dummy/.rspec
+- lib/api-versions/version_check.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/v3/bar_controller.rb
 - spec/dummy/app/controllers/application_controller.rb
 - spec/dummy/config.ru
 - spec/dummy/config/application.rb
@@ -81,10 +83,10 @@ signing_key:
 specification_version: 3
 summary: Allows you to cache routing and then inherit it in other modules.
 test_files:
-- spec/dummy/.rspec
 - 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/v3/bar_controller.rb
 - spec/dummy/app/controllers/application_controller.rb
 - spec/dummy/config.ru
 - spec/dummy/config/application.rb

data/spec/dummy/.rspec

@@ -1 +0,0 @@
---color