versionable_api 0.0.1

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2013 Chris TenHarmsel
+
+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

@@ -0,0 +1,110 @@
+# VersionableApi
+
+VersionableApi is a small gem that helps you create versionable apis (initially in Rails).
+
+# The Problem
+
+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
+```
+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
+```
+and you create `app/controllers/api/v2/people_controller.rb`.
+
+But do you make `Api::V2::PeopleController` inherit from `Api::V1::PeopleController`? Or do you copy/paste every method in the Version 1 controller to the Version 2 controller?
+
+# 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.
+
+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.
+
+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:
+```
+config.middleware.use "VersionableApi::ApiVersionInterceptor", {version_regex: /\/API\/version-(?<version>\d+)\/(?<path>.*)/}
+```
+would cause it to match paths like: `/API/version-10/something` instead.  See documentation in `lib/versionable_api/api_version_interceptor.rb` for details.
+
+# Example
+`PeopleController` with support for 2 versions of API
+```ruby
+class Api::PeopleController < ::ApplicationController
+  respond_to :json
+  include VersionableApi::ApiVersioning
+  include Api::V1::People
+  include Api::V2::People
+end
+```
+The first version:
+```ruby
+module Api::V1::People
+  def show_v1
+    respond_with People.first
+  end
+  def index_v1
+    respond_with People.all
+  end
+end
+```
+
+And the second version
+```ruby
+module Api::V2::People
+  def show_v2
+    respond_with People.where(email: "foo@bar.com")
+  end
+end
+```
+
+**An explicit version 2 request comes in:**
+```
+GET /api/people/1234.json {HTTP_ACCEPT: text/json;version=2}
+```
+the `Api::V2::People#show_v2` method will handle the request.
+
+**An explicit version 1 request comes in:**
+```
+GET /api/people/1234.json {HTTP_ACCEPT: text/json;version=1}
+```
+the `Api::V1::People#show_v1` method will handle the request.
+
+
+**However, if a request comes in that looks like this:**
+```
+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.
+
+
+# How to use it
+1. Add it to your `Gemfile`:
+    
+    ```
+    gem 'versionable_api'
+    ```
+2. Create API controllers that are not versioned: `Api::PeopleController` should be in `app/controllers/api/people_controller.rb`
+3. Include the `VersionableApi::ApiVersioning` module in your controller
+4. Add version identifiers to your action method names.  Instead of `def index; ... end;` you do `def index_v1; ... end;`.  You can put these in named modules to keep things tidy if you want, or just put them all in the base controller.
+5. Set up routes like there's no versioning:
+    
+    ```
+    namespace :api do 
+      resources :people
+    end
+    ```
+
+This project rocks and uses MIT-LICENSE.

data/Rakefile

@@ -0,0 +1,34 @@
+#!/usr/bin/env rake
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+begin
+  require 'rdoc/task'
+rescue LoadError
+  require 'rdoc/rdoc'
+  require 'rake/rdoctask'
+  RDoc::Task = Rake::RDocTask
+end
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'VersionableApi'
+  rdoc.options << '--line-numbers'
+  rdoc.rdoc_files.include('README.rdoc')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+Bundler::GemHelper.install_tasks
+
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = false
+end
+
+task :default => :test

data/lib/versionable_api/api_version_interceptor.rb

@@ -0,0 +1,48 @@
+# Public: Rack Middleware for massaging URIs with the version in the path into
+# bare resource URIs with the version specified in an Accept header.
+module VersionableApi
+  class ApiVersionInterceptor
+
+    # Public: Initialize the ApiVersionInterceptor
+    #
+    # app - Next Rack middleware app in the chain
+    # options - Options hash with these keys:
+    #   version_regex - Regular Expression that matches API requests in the "old"
+    #     format, should contain two named captures:
+    #       1. 'version' - The version number
+    #       2. 'path' - The API endpoint path
+    #   api_prefix - Prefix for resulting URIs, the API endpoint path from the matcher
+    #     will be appended to this to build the "real" uri
+    #   accept_header - The accept header that will have the version appended to it and
+    #     then will be prepended to the existing Accept headers on the request
+    #
+    # Example:
+    #   Incoming URI we want to massage: "/api/v1/thing.json"
+    #   Resulting URI we want to handle: "/api/thing.json", Accept Header: "*/*;version=1"
+    #
+    #   version_regex = /^\/api\/v(?<version>\d+)\/(?<path>.+)/
+    #   api_prefix = "/api"
+    #   accept_header = "*/*;version="
+    #
+    def initialize(app, options={})
+      options = {
+        version_regex: /^\/api\/v(?<version>\d+)\/(?<path>.+)/,
+        api_prefix: "/api",
+        accept_header: "*/*;version="
+      }.merge(options)
+
+      @app = app
+      @version_regex = options[:version_regex]
+      @api_prefix = options[:api_prefix]
+      @accept_header = options[:accept_header]
+    end
+
+    def call(env)
+      if m = env["PATH_INFO"].match(@version_regex)
+        env["PATH_INFO"] = "#{@api_prefix}/#{m[:path]}"
+        env["HTTP_ACCEPT"] = "#{@accept_header}#{m[:version]}, #{env['HTTP_ACCEPT']}"
+      end
+      @app.call env
+    end
+  end
+end

data/lib/versionable_api/api_versioning.rb

@@ -0,0 +1,49 @@
+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
+    #
+    # 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
+    # the containing class then this will behave in one of two ways:
+    #   1. If #action_missing is defined, this method will return "_handle_aciton_missing"
+    #      to stay in line with how the default Rails implementation works
+    #   2. If #action_missiong is not defined, then this will return nil (preserves)
+    #      default rails behavior)
+    #
+    # action - The name of the action to look up, a String
+    #
+    # 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
+      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
+    def requested_version
+      accept_headers = request.headers["HTTP_ACCEPT"]
+      return nil if accept_headers.nil?
+      parts = accept_headers.split(",").map(&:strip)
+      requested = parts.map{|part| part.match(/version=(\d+)/)[1] if part.match(/version=\d+/)}.detect{|i| !i.nil?}
+      requested.to_i unless requested.nil?
+    end
+
+  end
+end

data/lib/versionable_api/version.rb

@@ -0,0 +1,3 @@
+module VersionableApi
+  VERSION = "0.0.1"
+end

data/lib/versionable_api.rb

@@ -0,0 +1,4 @@
+require "versionable_api/api_versioning"
+require "versionable_api/api_version_interceptor"
+module VersionableApi
+end

data/test/spec/api_version_interceptor_test.rb

@@ -0,0 +1,56 @@
+require 'test_helper'
+
+describe VersionableApi::ApiVersionInterceptor do
+  describe "With defaults" do 
+    before do 
+      @app = MiniTest::Mock.new
+      @test_me = VersionableApi::ApiVersionInterceptor.new(@app)
+    end
+
+    it "should forward the request to the next app as-is if it doesn't match the default API path setup" do 
+      env = {"PATH_INFO" => "/something/foo.json", "HTTP_ACCEPT" => "*/*"}
+      @app.expect :call, true, [env]
+      @test_me.call(env)
+      @app.verify
+    end
+
+    it "should change an old API path to a new path with version specified in the header" do 
+      in_env = {"PATH_INFO" => "/api/v3/foo.json", "HTTP_ACCEPT" => "*/*"}
+      expected_env = {"PATH_INFO" => "/api/foo.json", "HTTP_ACCEPT" => "*/*;version=3, */*"}
+      @app.expect :call, true, [expected_env]
+      @test_me.call(in_env)
+      @app.verify
+    end
+
+    it "should not modify 'new' style API requests" do 
+      env = {"PATH_INFO" => "/api/foo.json", "HTTP_ACCEPT" => "*/*;version=3"}
+      @app.expect :call, true, [env]
+      @test_me.call(env)
+      @app.verify
+    end
+  end
+
+  describe "With modified options" do 
+    before do 
+      @app = MiniTest::Mock.new
+    end
+    
+    it "should allow a user to specify the regular expression used to identify API requests" do 
+      @test_me = VersionableApi::ApiVersionInterceptor.new(@app, {version_regex: /version_(?<version>\d+)\/(?<path>.+)/})
+      in_env = {"PATH_INFO" => "/version_3/foo.json", "HTTP_ACCEPT" => "*/*"}
+      expected_env = {"PATH_INFO" => "/api/foo.json", "HTTP_ACCEPT" => "*/*;version=3, */*"}
+      @app.expect :call, true, [expected_env]
+      @test_me.call(in_env)
+      @app.verify
+    end
+
+    it "should allow a user to specify old-stype API structure, new path and accept header structure" do 
+      @test_me = VersionableApi::ApiVersionInterceptor.new(@app, {version_regex: /version_(?<version>\d+)\/(?<path>.+)/, api_prefix: "/get_data", accept_header: "*/*;v="})
+      in_env = {"PATH_INFO" => "/version_3/foo.json", "HTTP_ACCEPT" => "*/*"}
+      expected_env = {"PATH_INFO" => "/get_data/foo.json", "HTTP_ACCEPT" => "*/*;v=3, */*"}
+      @app.expect :call, true, [expected_env]
+      @test_me.call(in_env)
+      @app.verify
+    end
+  end
+end

data/test/spec/versionable_api_test.rb

@@ -0,0 +1,74 @@
+require 'test_helper'
+require 'ostruct'
+
+describe VersionableApi::ApiVersioning do
+  class Testable 
+    include VersionableApi::ApiVersioning
+    attr_accessor :request
+    def initialize
+      @request = OpenStruct.new
+      @request.headers = {}
+    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
+  end
+
+  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 
+      assert_nil @test_me.requested_version
+    end
+
+    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 
+      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 
+      assert_equal "show_v1", @test_me.method_for_action("show")
+    end
+
+    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 
+      @test_me.request.headers["HTTP_ACCEPT"] = "*/*;version=10"
+      assert_equal "show_v2", @test_me.method_for_action("show")
+      @test_me.request.headers["HTTP_ACCEPT"] = "*/*;version=2"
+      assert_equal "index_v1", @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 
+      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 
+      @test_me.request.headers["HTTP_ACCEPT"] = "*/*;version=2"
+      assert_nil @test_me.method_for_action("foobar")
+    end
+  end
+end

data/test/test_helper.rb

@@ -0,0 +1,2 @@
+require 'minitest/autorun'
+require 'versionable_api'

metadata

@@ -0,0 +1,74 @@
+--- !ruby/object:Gem::Specification
+name: versionable_api
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+  prerelease: 
+platform: ruby
+authors:
+- Chris TenHarmsel
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-08-28 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Simple Gem that provides a framework for sane versionable APIs
+email:
+- chris.tenharmsel@centro.net
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/versionable_api/api_version_interceptor.rb
+- lib/versionable_api/api_versioning.rb
+- lib/versionable_api/version.rb
+- lib/versionable_api.rb
+- MIT-LICENSE
+- Rakefile
+- README.md
+- test/spec/api_version_interceptor_test.rb
+- test/spec/versionable_api_test.rb
+- test/test_helper.rb
+homepage: http://www.github.com/centro/versionable_api
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.23
+signing_key: 
+specification_version: 3
+summary: Versionable APIs
+test_files:
+- test/spec/api_version_interceptor_test.rb
+- test/spec/versionable_api_test.rb
+- test/test_helper.rb