api-responder 1.0.0

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/Gemfile

@@ -0,0 +1,15 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in api-responder.gemspec
+gemspec
+
+group :development, :test do
+  gem 'rake'
+  gem 'minitest'
+  gem 'minitest-ansi'
+  gem 'mocha', '>= 0.13', :require => false
+end
+
+group :test do
+  gem 'actionpack'
+end

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2013 Jan Graichen
+
+MIT License
+
+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,146 @@
+# Responders::ApiResponder
+
+`ApiResponder` simplifies version dependent rendering of API resources using a custom responder and a mixin for decorators or models (decorators are recommended).
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'api-responder'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install api-responder
+
+## Usage
+
+Add `Responders::ApiResponder` to your responder chain:
+
+```ruby
+class AppResponder < Responder
+  include Responders::ApiResponder
+end
+
+class MyController < ApplicationController
+  self.responder = ApiResponder
+end
+```
+
+Or use it with [plataformatec/responders](https://github.com/plataformatec/responders):
+
+```ruby
+class MyController < ApplicationController
+  responders Responders::ApiResponder
+end
+```
+
+This will add an API version parameter to the options hash for formatting methods like `as_json`. You can override the formatting methods or just include `ApiResponder::Formattable`:
+
+```ruby
+class MyModel
+  include ApiResponder::Formattable
+
+  api_formats :xml
+
+  def as_api_v1
+    {
+      id: id,
+      first_name: name.split.first
+      last_name: name.split.last
+    }
+  end
+
+  def as_api_v2
+    as_api_v1.merge name: "#{first_name} #{last_name}"
+  end
+end
+```
+
+This will add a handler for XML. You can specify any format your want. `ApiResponder::Formattable` will override the `to_{format}` (e.g. `to_xml`) method to call `to_{format}` on the API specific hash. JSON is supported via `as_json` by default.
+
+The only included method to detect API version is matching the URL path `/api/v(\d+)`. Or you can add an `api_version` method to your controller:
+
+```ruby
+class MyController < ApplicationController
+  responders Responders::ApiResponder
+
+  def api_version
+    return $1 if request.headers["Accept"] =~ /vnd\.myapp.v(\d+)/
+  end
+end
+```
+
+I recommend using `ApiResponder` in combination with [jgraichen/decorate-responder](/jgraichen/decorate-responder) and the decorator pattern (like [draper](/drapergem/draper)):
+
+```ruby
+class User < ActiveRecord::Base
+  attr_accessible :id, :first_name, :last_name
+end
+
+class UserDecorator < Draper::Decorator
+  include ApiResponder::Formattable
+  decorates :user
+
+  api_formats :msgpack
+
+  def name
+    "#{first_name} #{last_name}"
+  end
+
+  def as_api_v1
+    {
+      id: model.id,
+      created_at: model.created_at.utc.iso8601,
+      name: name
+    }
+  end
+end
+
+class UsersController < ApplicationController
+  responders Responders::ApiResponder,
+    Responders::DecorateResponder
+
+  respond_to :json, :xml, :msgpack
+  rescue_from ApiResponder::Formattable::UnsupportedVersion do
+    head :not_acceptable
+  end
+
+  def index
+    respond_with User.scoped
+  end
+
+  def api_version
+    return $1 if request.headers["Accept"] =~ /vnd\.myapp.v(\d+)/
+  end
+end
+```
+
+When `ApiResponder::Formattable` receives nil as API version or the resource does not have a matching `as_api_v` method an `UnsupportedVersion` error will be raised. You can catch that exception and for example return a `406` status code:
+
+```ruby
+rescue_from ApiResponder::Formattable::UnsupportedVersion do
+  head :not_acceptable
+end
+```
+
+Check out [jgraichen/paginate-responder](/jgraichen/paginate-responder) for automagic pagination support including HTTP Link headers.
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Write tests for your feature
+4. Add your feature
+5. Commit your changes (`git commit -am 'Add some feature'`)
+6. Push to the branch (`git push origin my-new-feature`)
+7. Create new Pull Request
+
+## License
+
+[MIT License](http://www.opensource.org/licenses/mit-license.php)
+
+Copyright (c) 2013 Jan Graichen

data/Rakefile

@@ -0,0 +1,10 @@
+require "bundler/gem_tasks"
+require 'rake/testtask'
+
+Rake::TestTask.new do |t|
+  t.libs.push "test"
+  t.test_files = FileList['test/*_test.rb']
+  t.verbose = true
+end
+
+task :default => :test

data/api-responder.gemspec

@@ -0,0 +1,21 @@
+# -*- encoding: utf-8 -*-
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'api-responder'
+
+Gem::Specification.new do |gem|
+  gem.name          = "api-responder"
+  gem.version       = ApiResponder::VERSION
+  gem.authors       = ["Jan Graichen"]
+  gem.email         = ["jg@altimos.de"]
+  gem.description   = %q{ApiResponder simplifies version dependent rendering of API resources.}
+  gem.summary       = %q{ApiResponder simplifies version dependent rendering of API resources.}
+  gem.homepage      = ""
+
+  gem.files         = `git ls-files`.split($/)
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.require_paths = ["lib"]
+
+  gem.add_dependency 'activesupport'
+end

data/lib/api-responder.rb

@@ -0,0 +1,10 @@
+require 'active_support/core_ext'
+
+module ApiResponder
+  autoload :VERSION, 'api-responder/version'
+  autoload :Formattable, 'api-responder/formattable'
+end
+
+module Responders
+  autoload :ApiResponder, 'responders/api_responder'
+end

data/lib/api-responder/formattable.rb

@@ -0,0 +1,44 @@
+module ApiResponder
+  module Formattable
+    class UnsupportedVersion < StandardError; end
+
+    module ClassMethods
+      def api_formats(*formats)
+        @api_formats ||= [ :json ]
+        return @api_formats if formats.empty?
+
+        formats.map!(&:to_sym)
+        formats -= @api_formats
+
+        formats.each do |format|
+          method = :"to_#{format}"
+          send :define_method, method do |options|
+            as_api(options.merge(:format => format)).send method, options
+          end
+          @api_formats << format
+        end
+      end
+    end
+
+    module InstanceMethods
+      def as_json(options)
+        as_api(options.merge(:format => :json)).as_json(options)
+      end
+
+      def as_api(options)
+        raise UnsupportedVersion.new unless options[:api_version]
+
+        method = :"as_api_v#{options[:api_version]}"
+        raise UnsupportedVersion.new unless respond_to? method
+
+        options.delete(:api_version)
+        return send method, options
+      end
+    end
+
+    def self.included(receiver)
+      receiver.extend         ClassMethods
+      receiver.send :include, InstanceMethods
+    end
+  end
+end

data/lib/api-responder/version.rb

@@ -0,0 +1,12 @@
+module ApiResponder
+  module VERSION
+    MAJOR = 1
+    MINOR = 0
+    PATCH = 0
+    STAGE = nil
+
+    def self.to_s
+      [MAJOR, MINOR, PATCH, STAGE].reject(&:nil?).join('.')
+    end
+  end
+end

data/lib/responders/api_responder.rb

@@ -0,0 +1,21 @@
+module Responders
+  module ApiResponder
+    def options
+      super.merge(api_options)
+    end
+
+    def api_options
+      { :api_version => api_version }
+    end
+
+    def api_version
+      return controller.api_version if controller.respond_to? :api_version
+      detect_api_version
+    end
+
+    def detect_api_version
+      return $1.to_i if request.path =~ /^\/api\/v(\d+)\//
+      nil
+    end
+  end
+end

data/test/api_responder_test.rb

@@ -0,0 +1,49 @@
+require 'test_helper'
+
+class ApiResponderTest < ActionController::TestCase
+  tests AppController
+
+  def setup
+    @resource = Resource.new
+  end
+
+  def test_formats_resource
+    get :index, :format => :json, :resource => Resource.new
+
+    assert_equal 406, response.status
+  end
+
+  def test_version_from_path
+    get :v2, :format => :json, :resource => Resource.new
+
+    assert_equal({"av" => 2}, JSON[response.body])
+  end
+
+  def test_custom_version
+    @controller = CustomController.new
+    @resource.expects(:as_api_v4).returns({"av" => "c4"})
+
+    request.env["HTTP_ACCEPT"] = "application/vnd.test.v4+json"
+    get :index, {:format => :json, :resource => @resource}
+
+    assert_equal({"av" => "c4"}, JSON[response.body])
+  end
+
+  def test_custom_version_nil
+    @controller = CustomController.new
+
+    request.env["HTTP_ACCEPT"] = "application/vnd.test.v+json"
+    get :index, {:format => :json, :resource => @resource}
+
+    assert_equal 406, response.status
+  end
+
+  def test_custom_version_unsupported
+    @controller = CustomController.new
+
+    request.env["HTTP_ACCEPT"] = "application/vnd.test.v6+json"
+    get :index, {:format => :json, :resource => @resource}
+
+    assert_equal 406, response.status
+  end
+end

data/test/formattable_test.rb

@@ -0,0 +1,63 @@
+require 'test_helper'
+
+describe ApiResponder::Formattable do
+  let(:resource)  { Object.new }
+  let(:cls)       { Class.new.tap { |c| c.send :include, ApiResponder::Formattable }}
+  let(:decorator) { cls.new }
+
+  describe "#api_formats" do
+    it "should have active json as default" do
+      assert_equal [ :json ], cls.api_formats
+    end
+
+    it "should return list of active formats" do
+      cls.api_formats :xml
+      assert_equal [ :json, :xml ], cls.api_formats
+    end
+
+    it "should have as_json method that delegates to as_api" do
+      decorator.expects(:as_api).with({:format => :json}).returns(resource)
+      resource.expects(:as_json).with({}).returns({})
+      decorator.as_json({})
+    end
+
+    it "should create to_format method that delegates to as_api" do
+      cls.api_formats :xml
+      decorator.expects(:as_api).with({:format => :xml}).returns(resource)
+      resource.expects(:to_xml).with({}).returns("")
+
+      decorator.to_xml({})
+    end
+  end
+
+  describe "#to_format" do
+    it "should merge options" do
+      cls.api_formats :xml
+      decorator.expects(:as_api).with({:format => :xml, :include_root => true}).returns(resource)
+      resource.expects(:to_xml).with({:include_root => true}).returns("")
+
+      decorator.to_xml({:include_root => true})
+    end
+  end
+
+  describe "#as_api" do
+    it "should delegate to to_api_v{api_version}" do
+      decorator.expects(:as_api_v2).with({:format => :json}).returns({})
+
+      decorator.as_api({:format => :json, :api_version => 2})
+    end
+
+    it "should raise exception if no version is given" do
+      assert_raises ApiResponder::Formattable::UnsupportedVersion do
+        decorator.as_api({:format => :json})
+      end
+    end
+
+    it "should raise exception if no version helper exists" do
+      assert_raises ApiResponder::Formattable::UnsupportedVersion do
+        decorator.as_api({:format => :json, :api_version => 4})
+      end
+    end
+  end
+end
+

data/test/test_helper.rb

@@ -0,0 +1,57 @@
+require 'minitest/autorun'
+require 'bundler'
+
+Bundler.setup
+
+# Configure Rails
+ENV["RAILS_ENV"] = "test"
+
+require 'mocha'
+require 'minitest/ansi'
+MiniTest::ANSI.use!
+
+require 'active_support'
+require 'action_controller'
+
+
+Responders::Routes = ActionDispatch::Routing::RouteSet.new
+Responders::Routes.draw do
+  match '/' => 'app#index'
+  match '/api/v1/index' => 'app#v1'
+  match '/api/v2/index' => 'app#v2'
+  match '/index' => 'custom#index'
+end
+
+class ActiveSupport::TestCase
+  setup do @routes = Responders::Routes end
+end
+
+class AppResponder < ActionController::Responder
+  include Responders::ApiResponder
+end
+
+class AppController < ActionController::Base
+  include Responders::Routes.url_helpers
+  self.responder = AppResponder
+  respond_to :json
+  rescue_from ApiResponder::Formattable::UnsupportedVersion do head :not_acceptable end
+  def index; respond_with params[:resource]; end
+  def v1; respond_with params[:resource]; end
+  def v2; respond_with params[:resource]; end
+end
+
+class CustomController < ActionController::Base
+  include Responders::Routes.url_helpers
+  self.responder = AppResponder
+  respond_to :json
+  rescue_from ApiResponder::Formattable::UnsupportedVersion do head :not_acceptable end
+  def index; respond_with params[:resource]; end
+  def api_version; return $1 if request.headers["Accept"] =~ /vnd\.test.v(\d+)/; end
+end
+
+class Resource
+  include ApiResponder::Formattable
+
+  def as_api_v1(opts); { :av => 1 }; end
+  def as_api_v2(opts); { :av => 2 }; end
+end

metadata

@@ -0,0 +1,83 @@
+--- !ruby/object:Gem::Specification
+name: api-responder
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+  prerelease: 
+platform: ruby
+authors:
+- Jan Graichen
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-02-11 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: ApiResponder simplifies version dependent rendering of API resources.
+email:
+- jg@altimos.de
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- api-responder.gemspec
+- lib/api-responder.rb
+- lib/api-responder/formattable.rb
+- lib/api-responder/version.rb
+- lib/responders/api_responder.rb
+- test/api_responder_test.rb
+- test/formattable_test.rb
+- test/test_helper.rb
+homepage: ''
+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'
+      segments:
+      - 0
+      hash: -1741048395832599252
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+      segments:
+      - 0
+      hash: -1741048395832599252
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.25
+signing_key: 
+specification_version: 3
+summary: ApiResponder simplifies version dependent rendering of API resources.
+test_files:
+- test/api_responder_test.rb
+- test/formattable_test.rb
+- test/test_helper.rb