acceptable_api 0.0.2 → 0.0.4

data/.rvmrc

@@ -0,0 +1,48 @@
+#!/usr/bin/env bash
+
+# This is an RVM Project .rvmrc file, used to automatically load the ruby
+# development environment upon cd'ing into the directory
+
+# First we specify our desired <ruby>[@<gemset>], the @gemset name is optional,
+# Only full ruby name is supported here, for short names use:
+#     echo "rvm use 1.9.3" > .rvmrc
+environment_id="ruby-1.9.3-p194@acceptable_api"
+
+# Uncomment the following lines if you want to verify rvm version per project
+# rvmrc_rvm_version="1.14.5 (stable)" # 1.10.1 seams as a safe start
+# eval "$(echo ${rvm_version}.${rvmrc_rvm_version} | awk -F. '{print "[[ "$1*65536+$2*256+$3" -ge "$4*65536+$5*256+$6" ]]"}' )" || {
+#   echo "This .rvmrc file requires at least RVM ${rvmrc_rvm_version}, aborting loading."
+#   return 1
+# }
+
+# First we attempt to load the desired environment directly from the environment
+# file. This is very fast and efficient compared to running through the entire
+# CLI and selector. If you want feedback on which environment was used then
+# insert the word 'use' after --create as this triggers verbose mode.
+if [[ -d "${rvm_path:-$HOME/.rvm}/environments"
+  && -s "${rvm_path:-$HOME/.rvm}/environments/$environment_id" ]]
+then
+  \. "${rvm_path:-$HOME/.rvm}/environments/$environment_id"
+  [[ -s "${rvm_path:-$HOME/.rvm}/hooks/after_use" ]] &&
+    \. "${rvm_path:-$HOME/.rvm}/hooks/after_use" || true
+else
+  # If the environment file has not yet been created, use the RVM CLI to select.
+  rvm --create  "$environment_id" || {
+    echo "Failed to create RVM environment '${environment_id}'."
+    return 1
+  }
+fi
+
+# If you use bundler, this might be useful to you:
+# if [[ -s Gemfile ]] && {
+#   ! builtin command -v bundle >/dev/null ||
+#   builtin command -v bundle | GREP_OPTIONS= \grep $rvm_path/bin/bundle >/dev/null
+# }
+# then
+#   printf "%b" "The rubygem 'bundler' is not installed. Installing it now.\n"
+#   gem install bundler
+# fi
+# if [[ -s Gemfile ]] && builtin command -v bundle >/dev/null
+# then
+#   bundle install | GREP_OPTIONS= \grep -vE '^Using|Your bundle is complete'
+# fi

data/README.md

@@ -2,7 +2,7 @@
 
 Build an acceptable API.
 
-HTTP is pretty darn awesome you guys. Part of HTTP - the `Accept` header -
+HTTP is pretty darn awesome you guys. Part of HTTP - `Accept` headers -
 allows the clients of our API to tell us what representation they want to work
 with. We should probably pay attention to them, hey?
 
@@ -33,13 +33,22 @@ Or install it yourself as:
 
     $ gem install acceptable_api
 
+
 ## Usage
 
-Assume you have a class that you want to expose via a lovely HTTP API.
+Assume you have a class that you want to expose via a lovely HTTP ReST API:
 
+    # app/models/sandwich.rb
     class Sandwich
-      def self.find id
-        # Look up a Sandwich by ID
+      attr_accessor :id
+      private :id=
+
+      def initialize id
+        self.id = id
+        self.bread = "Brown"
+        self.fillings = %w(mayo chicken salad)
+        self.name = "Chicken Mayo Salad"
+        self.made_at = Time.now
       end
 
       attr_accessor :fillings
@@ -48,35 +57,38 @@ Assume you have a class that you want to expose via a lovely HTTP API.
       attr_accessor :made_at
     end
 
-You'd declare that you wanted to expose it via the API as `/sandwiches/123` like
-this:
+You'd declare that you wanted to expose it via the API like this:
+
+    # app/resources/sandwich_resource.rb
+    class SandwichResource
+      include AcceptableApi::Controller
 
-    class SandwichApi < AcceptableApi::Controller
-      get '/sandwiches/:id' do
-        Sandwich.find params[:id]
+      def show_sandwich
+        # Normally this would be a database lookup but since this is just an
+        # example I create a new instance to keep things simple
+        Sandwich.new params[:id]
       end
     end
 
-Of course, this needs to be run somehow. An `AcceptableApi::Controller` can be
-used as a Rack application. In `config.ru` do this:
+Of course, this needs to be run somehow. I've chosen to do this via Rack. In
+`config.ru` do this:
 
     require 'acceptable_api'
-    require 'sandwich_api'
+    require 'app/models/sandwich'
+    require 'app/resource/sandwich_resource'
 
-    run SandwichApi
+    app = AcceptableApi::Builder.new
+    app.expose 'SandwichResource#show_sandwich', at: '/sandwiches/:id',
+                                                 via: 'get'
+    run app.to_app
 
 You can now use `rackup` as normal to launch a web server, and `curl` to access
-your API:
+your API, requesting a plain text representation of sandwich 123:
 
-    $ curl -i http://localhost:9292/sandwiches/123
+    $ curl  -H 'Accept: application/json' -i http://localhost:9292/sandwiches/123
     HTTP/1.1 406 Not Acceptable
-    X-Frame-Options: sameorigin
-    X-Xss-Protection: 1; mode=block
     Content-Type: application/javascript
     Content-Length: 21
-    Server: WEBrick/1.3.1 (Ruby/1.9.2/2011-07-09)
-    Date: Sat, 21 Apr 2012 19:57:59 GMT
-    Connection: Keep-Alive
 
     {
       "links": [
@@ -85,53 +97,45 @@ your API:
     }
 
 We got a `406 Not Acceptable` response because AcceptableApi doesn't know how to
-respond with any of the representations we'd accept. That's fair: we haven't
-told it how to respond to /any/ representations yet. Do it like this:
+respond with an `application/json` representation of a Sandwich. That's fair: we
+haven't told it how to respond with /any/ representations of sandwiches yet. Do
+it like this in `config.ru`, before calling `#to_app`:
 
-    AcceptableApi.register Sandwich, 'application/json' do |sandwich, request|
+    app.register Sandwich => 'application/json' do |sandwich|
       JSON.generate :id => sandwich.id
     end
 
 Let's try requesting the resource again:
 
-    $ curl -i http://localhost:9293/sandwiches/123
+    $ curl -H 'Accept: application/json' -i http://localhost:9292/sandwiches/123
     HTTP/1.1 200 OK
-    X-Frame-Options: sameorigin
-    X-Xss-Protection: 1; mode=block
     Content-Type: application/json
     Content-Length: 12
-    Server: WEBrick/1.3.1 (Ruby/1.9.2/2011-07-09)
-    Date: Sat, 21 Apr 2012 20:03:14 GMT
-    Connection: Keep-Alive
 
     {"id":"123"}
 
-Ace, we got a response. What happens if we ask for a plain text response?
+Ace, we got a response, and it's the JSON represenation of the sandwich. What
+happens if we ask for a plain text representation?
 
     $ curl -H 'Accept: text/plain' -i http://localhost:9292/sandwiches/123
     HTTP/1.1 406 Not Acceptable
-    X-Frame-Options: sameorigin
-    X-Xss-Protection: 1; mode=block
     Content-Type: application/javascript
     Content-Length: 146
-    Server: WEBrick/1.3.1 (Ruby/1.9.2/2011-07-09)
-    Date: Sat, 21 Apr 2012 20:04:46 GMT
-    Connection: Keep-Alive
 
     {
       "links": [
-	{
-	  "rel": "alternative",
-	  "type": "application/json",
-	  "uri": "http://localhost:9293/sandwiches/123"
-	}
+        {
+          "rel": "alternative",
+          "type": "application/json",
+          "uri": "http://localhost:9292/sandwiches/123"
+        }
       ]
     }
 
 As expected, this is a `406 Not Acceptable` response, but we take the
 opportunity to provide a list of alternative representations that the client may
-want to check out. Our `application/json` is listed with the type and the URI to
-request should the client want to do so.
+want to check out. The `application/json` representation is listed with the type
+and the URI to request should the client want to do so.
 
 Time passes, and a we decide that our API would be more useful if it returned
 the fillings and bread used in the sandwich, and we want to replace the database
@@ -150,18 +154,31 @@ which specifies the returned document:
 
 And we register the type with AcceptableApi:
 
-    AcceptableApi.register Sandwich, 'application/vnd.acme.sandwich-v1+json' do |sandwich, request|
+    app.register Sandwich => 'application/vnd.acme.sandwich-v1+json' do |sandwich|
       JSON.generate :name => sandwich.name, :fillings => sandwich.fillings,
         :bread => sandwich.bread
     end
 
 And we make the request:
 
-    
+    $  curl -H 'Accept: application/vnd.acme.sandwich-v1+json' -i http://localhost:9292/sandwiches/123
+    HTTP/1.1 200 OK
+    Content-Type: application/vnd.acme.sandwich-v1+json
+    Content-Length: 75
+
+    {"name":"Bleaugh","fillings":["jam","avacado","anchovies"],"bread":"brown"}
+
+Making a request for the normal `application/json` representation still works:
+
+    $ curl -H 'Accept: application/json' -i http://localhost:9292/sandwiches/123
+    HTTP/1.1 200 OK
+    Content-Type: application/json
+    Content-Length: 12
+
+    {"id":"123"}
 
-See `example/example.rb` for an example.
+See the example directory, `example/`, for a working example.
 
-TODO: Write usage instructions here
 
 ## Contributing
 
@@ -170,3 +187,54 @@ TODO: Write usage instructions here
 3. Commit your changes (`git commit -am 'Added some feature'`)
 4. Push to the branch (`git push origin my-new-feature`)
 5. Create new Pull Request
+
+
+## TODO
+
+* Still need to add tests and discover how to work with the other HTTP verbs,
+  starting with POST, PUT, DELETE and OPTIONS. HEAD could be handy as well but
+  it's quite possible that software further up the stack could just strip out
+  the GET entity to create a valid HEAD response. As a first scratch I'm
+  imagining changing the #expose call to something like:
+
+    app.expose SandwichResource, at: '/sandwiches/:id',
+      get: 'show', put: 'update', delete: 'destroy'
+
+* I don't like defining the conversions in`config.ru`. It would be lovely if
+  these could be picked up automatically on start-up - but I'd settle for
+  something less verbose that I currently have. Possibly a slight adaptation of
+  the expose call:
+
+    app.expose Sandwich, at: '/sandwiches/:id',
+      get: 'show', put: 'update', delete: 'destroy'
+
+  This could guess we want the use `SandwichResource` as the controller, and it
+  could examine `app/views/sandwiches/**/*.rb` for convertors:
+
+    convert Sandwich => 'application/vnd.acme.sandwich-v1+xml' do |sandwich|
+      xml = Builder::XmlMarkup.new
+      xml.sandwich do |s|
+        s.name sandwich.name
+        s.bread sandwich.bread
+        s.fillings do |f|
+          sandwich.fillings.each do |filling|
+            f.filling filling
+          end
+        end
+      end
+    end
+
+* Need to work out how I should deal with authentication etc. Want to keep
+  this clean. A controller should be able to return any of the HTTP statuses
+  that makes sense, including 401 / 403.
+
+
+## Authors
+
+Craig R Webster <craig@barkingiguana.com>
+
+
+## Licence
+
+Released under the terms of the MIT licence, a copy of which can be found in the
+`LICENCE` file distributed with this project.

data/Rakefile

@@ -1,2 +1,12 @@
 #!/usr/bin/env rake
-require "bundler/gem_tasks"
+require 'bundler/gem_tasks'
+require 'rake/testtask'
+
+Rake::TestTask.new do |t|
+  t.libs << "test"
+  t.test_files = FileList['test/**/*_test.rb']
+  t.verbose = true
+end
+
+desc "Run tests"
+task :default => :test

data/acceptable_api.gemspec

@@ -4,7 +4,7 @@ require File.expand_path('../lib/acceptable_api/version', __FILE__)
 Gem::Specification.new do |gem|
   gem.authors       = ["Craig R Webster"]
   gem.email         = ["craig@barkingiguana.com"]
-  gem.description   = %q{HTTP lets clients sned an Accept header. We should probably use that to accept more than the bog-standard mime-types.}
+  gem.description   = %q{HTTP lets clients send Accept headers. We should probably use that to work out what they'll accept as a response, yea?}
   gem.summary       = %q{Build an Acceptable API}
   gem.homepage      = "http://barkingiguana.com/2011/12/05/principles-of-service-design-program-to-an-interface/"
 
@@ -14,8 +14,12 @@ Gem::Specification.new do |gem|
   gem.name          = "acceptable_api"
   gem.require_paths = ["lib"]
   gem.version       = AcceptableApi::VERSION
+  gem.add_runtime_dependency 'json'
   gem.add_runtime_dependency 'rack'
   gem.add_runtime_dependency 'rack-accept'
   gem.add_runtime_dependency 'rack-accept-header-updater'
-  gem.add_runtime_dependency 'sinatra'
+
+  gem.add_development_dependency 'rack-test'
+  gem.add_development_dependency 'test-unit'
+  gem.add_development_dependency 'rake'
 end

data/example/Gemfile

@@ -1,10 +1,4 @@
 source :rubygems
 
-gem 'acceptable_api'
-gem 'sinatra'
-gem 'rack'
-gem 'rack-accept-header-updater'
-gem 'rack-accept'
-gem 'rake'
-
+gemspec :path => '../'
 gem 'builder'

data/example/config.ru

@@ -1,4 +1,43 @@
 require 'acceptable_api'
 require './example'
 
-run Example
+require 'json'
+require 'builder'
+
+app = AcceptableApi::Builder.new
+
+app.register Sandwich => 'text/plain' do |sandwich|
+  s = []
+  s << sandwich.name
+  s << sandwich.fillings.sort.join(',')
+  s << sandwich.bread
+  s << sandwich.made_at.iso8601
+  s.join "\n"
+end
+
+app.register Sandwich => 'application/vnd.acme.sandwich-v1+xml' do |sandwich|
+  xml = Builder::XmlMarkup.new
+  xml.sandwich do |s|
+    s.name sandwich.name
+    s.bread sandwich.bread
+    s.fillings do |f|
+      sandwich.fillings.each do |filling|
+        f.filling filling
+      end
+    end
+  end
+end
+
+app.register Sandwich => 'application/json' do |sandwich|
+  JSON.generate :id => sandwich.id
+end
+
+app.register Sandwich => 'application/vnd.acme.sandwich-v1+json' do |sandwich|
+  JSON.generate :name => sandwich.name, :fillings => sandwich.fillings,
+    :bread => sandwich.bread
+end
+
+app.expose 'SandwichResource#show_sandwich', at: '/sandwiches/:id',
+                                             via: 'get'
+
+run app.to_app

data/example/example.rb

@@ -1,41 +1,27 @@
-require 'ostruct'
-require 'json'
-require 'builder'
+class Sandwich
+  attr_accessor :id
+  private :id=
 
-# One of the resources we're working with.
-# For simplicity I'm faking it out using OpenStruct.
-class Sandwich < OpenStruct
-  # Look up a Sandwich by ID
-  def self.find id
-    new :fillings => %w(jam avacado anchovies), :bread => "brown",
-      :made_at => Time.now, :id => id, :name => "Bleaugh"
+  def initialize id
+    self.id = id
+    self.bread = "Brown"
+    self.fillings = %w(mayo chicken salad)
+    self.name = "Chicken Mayo Salad"
+    self.made_at = Time.now
   end
-end
-
-AcceptableApi.register Sandwich, 'application/json' do |sandwich, request|
-  JSON.generate :id => sandwich.id
-end
 
-AcceptableApi.register Sandwich, 'application/vnd.acme.sandwich-v1+json' do |sandwich, request|
-  JSON.generate :name => sandwich.name, :fillings => sandwich.fillings,
-    :bread => sandwich.bread
+  attr_accessor :fillings
+  attr_accessor :bread
+  attr_accessor :name
+  attr_accessor :made_at
 end
 
-AcceptableApi.register Sandwich, 'application/vnd.acme.sandwich-v1+xml' do |sandwich, request|
-  xml = Builder::XmlMarkup.new
-  xml.sandwich do |s|
-    s.name sandwich.name
-    s.bread sandwich.bread
-    s.fillings do |f|
-      sandwich.fillings.each do |filling|
-        f.filling filling
-      end
-    end
-  end
-end
+class SandwichResource
+  include AcceptableApi::Controller
 
-class Example < AcceptableApi::Controller
-  get '/sandwiches/:id' do
-    Sandwich.find params[:id]
+  def show_sandwich
+    # Normally this would be a database lookup but since this is just an
+    # example I create a new instance to keep things simple
+    Sandwich.new params[:id]
   end
 end

data/lib/acceptable_api.rb

@@ -1,158 +1,21 @@
-require 'sinatra'
 require 'singleton'
+require 'json'
 require 'rack/accept'
 require 'rack/accept_header_updater'
 
-require "acceptable_api/version"
+require 'acceptable_api/accepts.rb'
+require 'acceptable_api/action.rb'
+require 'acceptable_api/application.rb'
+require 'acceptable_api/builder.rb'
+require 'acceptable_api/controller.rb'
+require 'acceptable_api/mapper.rb'
+require 'acceptable_api/mappers.rb'
+require 'acceptable_api/missing_controller.rb'
+require 'acceptable_api/missing_mapper.rb'
+require 'acceptable_api/missing_route.rb'
+require 'acceptable_api/route.rb'
+require 'acceptable_api/routes.rb'
+require 'acceptable_api/version.rb'
 
 module AcceptableApi
-  def self.register klass, mime_type, &map_block
-    Mapper.register klass, mime_type, &map_block
-  end
-
-  class MissingMapper
-    include Singleton
-
-    def mime_type
-      'application/javascript'
-    end
-
-    def execute resource, request
-      # set the response to "no acceptable representation available"
-      mappers = Mapper.for resource.class
-      body = {
-	:links => mappers.mime_types.map do |mime_type|
-	  { :rel => "alternative", :type => mime_type, :uri => request.uri }
-	end
-      }
-      [ 406, { 'Content-Type' => 'application/javascript' }, JSON.pretty_generate(body) ]
-    end
-  end
-
-  class Mappers
-    attr_accessor :mappers
-    private :mappers=, :mappers
-
-    def initialize mappers
-      self.mappers = mappers
-    end
-
-    def to accepts
-      acceptable_mime_types = accepts.order mime_types
-      acceptable_mappers = acceptable_mime_types.map { |mt|
-	mappers.detect { |m| m.mime_type == mt }
-      }
-      return acceptable_mappers if acceptable_mappers.any?
-      [ MissingMapper.instance ]
-    end
-
-    def mime_types
-      mappers.map { |m| m.mime_type }.sort.uniq
-    end
-  end
-
-  class Mapper
-    [ :klass, :mime_type, :map_block ].each do |a|
-      attr_accessor a
-      private "#{a}="
-    end
-    private :map_block
-
-    def initialize klass, mime_type, &map_block
-      self.klass = klass
-      self.mime_type = mime_type
-      self.map_block = map_block
-    end
-
-    def execute resource, request
-      body = map_block.call resource, request
-      [ status, headers, body ]
-    end
-
-    def status
-      200
-    end
-
-    def headers
-      { 'Content-Type' => mime_type }
-    end
-
-    def self.for klass
-      klass_mappers = mappers.select { |m| m.klass == klass }
-      Mappers.new klass_mappers
-    end
-
-    class << self;
-      attr_accessor :mappers
-      protected :mappers=, :mappers
-    end
-    self.mappers = []
-
-    def self.register klass, mime_type, &map_block
-      mapper = Mapper.new klass, mime_type, &map_block
-      self.mappers << mapper
-    end
-  end
-
-  # This needs to mimic as much of the Sinatra API as we use.
-  # Probably we want to set headers and content_type, not sure what else.
-  class Response
-    attr_accessor :params
-    def initialize options = {}
-      self.params = options[:params]
-    end
-  end
-
-  class Accepts
-    attr_accessor :request
-    private :request=, :request
-
-    def initialize env
-      self.request = Rack::Accept::Request.new env
-    end
-
-    def order mime_types
-      ordered = request.media_type.sort_with_qvalues mime_types, false
-      ordered.map! { |q, mt| mt }
-      ordered
-    end
-  end
-
-  class Request
-    attr_accessor :request
-    private :request=, :request
-
-    def initialize rack_request
-      self.request = rack_request
-    end
-
-    def respond_with resource
-      accepts = Accepts.new request.env
-      mappers = Mapper.for(resource.class).to(accepts)
-      mapper = mappers[0]
-      code, headers, body = mapper.execute resource, self
-      headers["Content-Length"] = body.bytesize.to_s
-      [ code, headers, body ]
-    end
-
-    def uri
-      request.url
-    end
-  end
-
-  class Controller < Sinatra::Base
-    use Rack::AcceptHeaderUpdater
-
-    def self.get path, &block
-      super path do
-	response = Response.new :params => params
-	resource = response.instance_eval &block
-	api = Request.new request
-	s, h, body = api.respond_with resource
-	status s
-	headers h
-	body
-      end
-    end
-  end
 end

data/lib/acceptable_api/accepts.rb

@@ -0,0 +1,16 @@
+module AcceptableApi
+  class Accepts
+    attr_accessor :request
+    private :request=, :request
+
+    def initialize env
+      self.request = Rack::Accept::Request.new env
+    end
+
+    def order mime_types
+      ordered = request.media_type.sort_with_qvalues mime_types, false
+      ordered.map! { |q, mt| mt }
+      ordered
+    end
+  end
+end

data/lib/acceptable_api/action.rb

@@ -0,0 +1,43 @@
+module AcceptableApi
+  class Action
+    attr_accessor :route
+    private :route=, :route
+
+    attr_accessor :request
+    private :request=, :request
+
+    attr_accessor :mappers
+    private :mappers=, :mappers
+
+    def initialize route, request, mappers
+      self.route = route
+      self.request = request
+      self.mappers = mappers
+    end
+
+    def execute
+      resource = controller.perform_action
+      resource_mappers = mappers.from resource.class
+      mapper = resource_mappers.to acceptable_mime_types
+      if mapper.missing?
+        body = {
+          :links => resource_mappers.mime_types.map do |mime_type|
+            { :rel => "alternative", 'Content-Type' => mime_type, :uri => request.url, :method => request.request_method }
+          end
+        }
+        [ 406, { 'Content-Type' => 'application/json' }, [ JSON.pretty_generate(body) ] ]
+      else
+        body = mapper.execute resource, request
+        [ 200, { 'Content-Type' => mapper.to }, [ body ] ]
+      end
+    end
+
+    def controller
+      route.controller_for_request request
+    end
+
+    def acceptable_mime_types
+      Accepts.new request.env
+    end
+  end
+end

data/lib/acceptable_api/application.rb

@@ -0,0 +1,26 @@
+module AcceptableApi
+  class Application
+    attr_accessor :routes
+    protected :routes=, :routes
+
+    attr_accessor :mappers
+    protected :mappers=, :mappers
+
+    def initialize mappers, routes
+      self.mappers = mappers
+      self.routes = routes
+    end
+
+    def call env
+      request = Rack::Request.new env
+      action = action_for request
+      action.execute
+    end
+
+    def action_for request
+      route = routes.for request
+      Action.new route, request, mappers
+    end
+    private :action_for
+  end
+end

data/lib/acceptable_api/builder.rb

@@ -0,0 +1,31 @@
+module AcceptableApi
+  class Builder
+    attr_accessor :mappers
+    protected :mappers=, :mappers
+
+    attr_accessor :routes
+    protected :routes=, :routes
+
+    def initialize
+      self.mappers = Mappers.new
+      self.routes = Routes.new
+    end
+
+    def register from_to, &map_block
+      from = from_to.keys[0]
+      to = from_to.values[0]
+      mapper = Mapper.new from, to, &map_block
+      self.mappers << mapper
+    end
+
+    def expose controller_action, options = {}
+      route = Route.new options, controller_action
+      self.routes << route
+    end
+
+    def to_app
+      Application.new mappers, routes
+    end
+  end
+end
+

data/lib/acceptable_api/controller.rb

@@ -0,0 +1,18 @@
+module AcceptableApi
+  module Controller
+    attr_accessor :params
+    protected :params, :params=
+
+    attr_accessor :action
+    protected :action, :action=
+
+    def initialize params, action
+      self.params = params
+      self.action = action
+    end
+
+    def perform_action
+      send action
+    end
+  end
+end

data/lib/acceptable_api/mapper.rb

@@ -0,0 +1,31 @@
+module AcceptableApi
+  class Mapper
+    [ :from, :to, :map_block ].each do |a|
+      attr_accessor a
+      private "#{a}="
+    end
+    private :map_block
+
+    def missing?
+      false
+    end
+
+    def initialize from, to, &map_block
+      self.from = from
+      self.to = to
+      self.map_block = map_block
+    end
+
+    def from? desired
+      from == desired
+    end
+
+    def to? desired
+      to == desired
+    end
+
+    def execute resource, request
+      map_block.call resource, request
+    end
+  end
+end

data/lib/acceptable_api/mappers.rb

@@ -0,0 +1,36 @@
+module AcceptableApi
+  class Mappers
+    attr_accessor :mappers
+    private :mappers=, :mappers
+
+    def initialize mappers = []
+      self.mappers = mappers
+    end
+
+    def << mapper
+      mappers << mapper
+    end
+
+    def from what
+      Mappers.new mappers.select { |m| m.from? what }
+    end
+
+    def to accepts
+      acceptable_mime_types = accepts.order mime_types
+      mapper = acceptable_mime_types.map { |mt|
+	mappers.detect { |m| m.to? mt }
+      }[0]
+      return mapper unless mapper.nil?
+      MissingMapper.instance
+    end
+
+    def mime_types
+      mappers.map { |m| m.to }.sort.uniq
+    end
+
+    def each &block
+      mappers.each &block
+    end
+    include Enumerable
+  end
+end

data/lib/acceptable_api/missing_controller.rb

@@ -0,0 +1,8 @@
+module AcceptableApi
+  class MissingController
+    include Singleton
+
+    def perform_action
+    end
+  end
+end

data/lib/acceptable_api/missing_mapper.rb

@@ -0,0 +1,9 @@
+module AcceptableApi
+  class MissingMapper
+    include Singleton
+
+    def missing?
+      true
+    end
+  end
+end

data/lib/acceptable_api/missing_route.rb

@@ -0,0 +1,9 @@
+module AcceptableApi
+  class MissingRoute
+    include Singleton
+
+    def controller_for_request request
+      MissingController.instance
+    end
+  end
+end

data/lib/acceptable_api/route.rb

@@ -0,0 +1,50 @@
+module AcceptableApi
+  class Route
+    [ :controller_action, :constraints ].each do |a|
+      attr_accessor a
+      private "#{a}=", a
+    end
+
+    def initialize constraints, controller_action
+      self.constraints = constraints
+      self.controller_action = controller_action
+    end
+
+    def match? request
+      return false unless constraints[:via].upcase == request.request_method
+      return false unless path_regex.match request.path
+      true
+    end
+
+    def path_regex
+      named_captures = constraints[:at].gsub /\:([^\/]+)/, '(?<\1>[^\/]+)'
+      Regexp.new "^#{named_captures}$"
+    end
+
+    def params_from request
+      matches = path_regex.match request.path
+      matches.names.inject({}) { |a,e|
+        a.merge! e.to_sym => matches[e]
+        a
+      }
+    end
+
+    def controller_for_request request
+      controller_class.new params_from(request), controller_method
+    end
+
+    def controller_class
+      controller_class_name.split(/::/).inject(Object) { |scope, const_name|
+        scope.const_get const_name
+      }
+    end
+
+    def controller_class_name
+      controller_action.split(/#/, 2)[0]
+    end
+
+    def controller_method
+      controller_action.split(/#/, 2)[-1]
+    end
+  end
+end

data/lib/acceptable_api/routes.rb

@@ -0,0 +1,20 @@
+module AcceptableApi
+  class Routes
+    attr_accessor :routes
+    private :routes=, :routes
+
+    def initialize routes = []
+      self.routes = routes
+    end
+
+    def << route
+      routes << route
+    end
+
+    def for request
+      route = routes.detect { |m| m.match? request }
+      return MissingRoute.instance unless route
+      route
+    end
+  end
+end

data/lib/acceptable_api/version.rb

@@ -1,3 +1,3 @@
 module AcceptableApi
-  VERSION = "0.0.2"
+  VERSION = "0.0.4"
 end

data/test/acceptance/request_different_mime_type_versions_test.rb

@@ -0,0 +1,15 @@
+require 'acceptance/test_helper'
+
+class RequestDifferentMimeTypeVersionsTest < AcceptableApi::AcceptanceTest
+  test "the correct representation is returned" do
+    header 'Accept', 'application/vnd.acceptable-api.example-v1+txt'
+    get '/example/123'
+    assert_equal 'Ducks token 123', last_response.body
+    assert_equal 'application/vnd.acceptable-api.example-v1+txt', last_response.headers['Content-Type']
+
+    header 'Accept', 'application/vnd.acceptable-api.example-v2+txt'
+    get '/example/123'
+    assert_equal 'Chickens token 123', last_response.body
+    assert_equal 'application/vnd.acceptable-api.example-v2+txt', last_response.headers['Content-Type']
+  end
+end

data/test/acceptance/request_unknown_mime_type_test.rb

@@ -0,0 +1,29 @@
+# We can't generate an entity body that's acceptable for the client.
+# http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.7
+class RequestUnknowntMimeTypeTest < AcceptableApi::AcceptanceTest
+  test "the correct status code is returned" do
+    header 'Accept', 'application/pdf'
+    get '/example/123'
+    assert_equal 406, last_response.status
+  end
+
+  test "a JSON list of alternatives is returned" do
+    header 'Accept', 'application/pdf'
+    get '/example/123'
+    assert_equal 'application/json', last_response.header['Content-Type']
+    json = JSON.parse last_response.body
+    links = json["links"]
+    assert_equal links.size, 2, "I expected only two links"
+    v1 = links.detect { |l| l["Content-Type"] == "application/vnd.acceptable-api.example-v1+txt" }
+    assert_not_nil v1, "Expected a link with Content-Type 'application/vnd.acceptable-api.example-v1+txt'"
+    assert_equal last_request.url, v1['uri']
+    assert_equal 'GET', v1['method']
+    assert_equal 'alternative', v1['rel']
+
+    v2 = links.detect { |l| l["Content-Type"] == "application/vnd.acceptable-api.example-v2+txt" }
+    assert_not_nil v2, "Expected a link with Content-Type 'application/vnd.acceptable-api.example-v2+txt'"
+    assert_equal last_request.url, v2['uri']
+    assert_equal 'GET', v2['method']
+    assert_equal 'alternative', v2['rel']
+  end
+end

data/test/acceptance/test_helper.rb

@@ -0,0 +1,47 @@
+require 'test_helper'
+
+module AcceptableApi
+  class AcceptanceTest < Test::Unit::TestCase
+    include Rack::Test::Methods
+
+    class Example
+      attr_accessor :token
+      private :token=, :token
+
+      def initialize token
+	self.token = token
+      end
+
+      def self.find token
+	# Normally this would load the resource from the data store
+	new token
+      end
+
+      def to_s
+	"token #{token}"
+      end
+    end
+
+    class ExampleResource
+      include AcceptableApi::Controller
+
+      def show
+	Example.find params[:token]
+      end
+    end
+
+    def app
+      a = AcceptableApi::Builder.new
+      a.register Example => 'application/vnd.acceptable-api.example-v1+txt' do |ex|
+	'Ducks ' + ex.to_s
+      end
+
+      a.register Example => 'application/vnd.acceptable-api.example-v2+txt' do |ex|
+	'Chickens ' + ex.to_s
+      end
+
+      a.expose 'AcceptableApi::AcceptanceTest::ExampleResource#show', at: '/example/:token', via: 'get'
+      a.to_app
+    end
+  end
+end

data/test/test_helper.rb

@@ -0,0 +1,9 @@
+require 'test/unit'
+require 'rack/test'
+require 'acceptable_api'
+
+Test::Unit::TestCase.class_eval do
+  def self.test name, &block
+    define_method "test #{name}", &block
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: acceptable_api
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.0.4
   prerelease: 
 platform: ruby
 authors:
@@ -9,11 +9,27 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-04-21 00:00:00.000000000Z
+date: 2012-07-29 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: json
+  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'
 - !ruby/object:Gem::Dependency
   name: rack
-  requirement: &70108579929200 !ruby/object:Gem::Requirement
+  requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -21,10 +37,15 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *70108579929200
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: rack-accept
-  requirement: &70108576320140 !ruby/object:Gem::Requirement
+  requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -32,10 +53,15 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *70108576320140
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: rack-accept-header-updater
-  requirement: &70108576318020 !ruby/object:Gem::Requirement
+  requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -43,20 +69,62 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *70108576318020
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
-  name: sinatra
-  requirement: &70108576317600 !ruby/object:Gem::Requirement
+  name: rack-test
+  requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
-  type: :runtime
+  type: :development
   prerelease: false
-  version_requirements: *70108576317600
-description: HTTP lets clients sned an Accept header. We should probably use that
-  to accept more than the bog-standard mime-types.
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: test-unit
+  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'
+- !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: HTTP lets clients send Accept headers. We should probably use that to
+  work out what they'll accept as a response, yea?
 email:
 - craig@barkingiguana.com
 executables: []
@@ -64,6 +132,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - .gitignore
+- .rvmrc
 - Gemfile
 - LICENSE
 - README.md
@@ -75,7 +144,23 @@ files:
 - example/config.ru
 - example/example.rb
 - lib/acceptable_api.rb
+- lib/acceptable_api/accepts.rb
+- lib/acceptable_api/action.rb
+- lib/acceptable_api/application.rb
+- lib/acceptable_api/builder.rb
+- lib/acceptable_api/controller.rb
+- lib/acceptable_api/mapper.rb
+- lib/acceptable_api/mappers.rb
+- lib/acceptable_api/missing_controller.rb
+- lib/acceptable_api/missing_mapper.rb
+- lib/acceptable_api/missing_route.rb
+- lib/acceptable_api/route.rb
+- lib/acceptable_api/routes.rb
 - lib/acceptable_api/version.rb
+- test/acceptance/request_different_mime_type_versions_test.rb
+- test/acceptance/request_unknown_mime_type_test.rb
+- test/acceptance/test_helper.rb
+- test/test_helper.rb
 homepage: http://barkingiguana.com/2011/12/05/principles-of-service-design-program-to-an-interface/
 licenses: []
 post_install_message: 
@@ -88,16 +173,26 @@ required_ruby_version: !ruby/object:Gem::Requirement
   - - ! '>='
     - !ruby/object:Gem::Version
       version: '0'
+      segments:
+      - 0
+      hash: 4567978281283614839
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
   - - ! '>='
     - !ruby/object:Gem::Version
       version: '0'
+      segments:
+      - 0
+      hash: 4567978281283614839
 requirements: []
 rubyforge_project: 
-rubygems_version: 1.8.10
+rubygems_version: 1.8.24
 signing_key: 
 specification_version: 3
 summary: Build an Acceptable API
-test_files: []
+test_files:
+- test/acceptance/request_different_mime_type_versions_test.rb
+- test/acceptance/request_unknown_mime_type_test.rb
+- test/acceptance/test_helper.rb
+- test/test_helper.rb