described_routes 0.6.1 → 0.7.0

data/History.txt

@@ -1,3 +1,7 @@
+== 0.7.0 2009-07-26
+
+* Discovery protocol via link headers
+
 == 0.6.1 2009-06-28
 
 * Add all_preorder and all_postorder to ResourceTemplate and ResourceTemplates

data/README.rdoc

@@ -2,9 +2,11 @@
 
 == DESCRIPTION
 
-Dynamic, framework-neutral metadata describing path/URI structures, with natural translations to/from JSON, YAML and XML.  Bonus features: easy Rails integration, link element / link header generation and a plain text report format!
-
-See roadmap for described_routes and path-to[http://github.com/asplake/path-to/tree] at http://positiveincline.com/?p=213.
+Features:
+* Dynamic, framework-neutral, client-friendly <code>ResourceTemplate</code> metadata describing the path/URI structures of your whole site or of specific resources
+* JSON, YAML and XML formats, also a bonus plain text report
+* A link header-based discovery protocol, enabling clients to find <code>ResourceTemplate</code> metadata from the resources of any enabled controller
+* Easy integration with Rails
 
 == SYNOPSIS:
 
@@ -58,29 +60,35 @@ include full URI templates.
 
 === Run time
 
-Include the controller, perhaps in an initializer:
+There are two integration steps for run time support:
+
+1) Include the controller, perhaps in an initializer:
 
   require 'described_routes/rails_controller'
 
-Add the following route in config/routes.rb:
+2) Add the following route in config/routes.rb:
 
   map.resources :described_routes, :controller => "described_routes/rails"
 
 You (or your client application) can now browse to any of the following top level addresses:
 
+* .../described_routes
+* .../described_routes.txt
 * .../described_routes.json
 * .../described_routes.xml
 * .../described_routes.yaml
-* .../described_routes.ytxt
 
 and for the named route "users" (say):
 
+* .../described_routes/users
+* .../described_routes/users.txt
 * .../described_routes/users.json
 * .../described_routes/users.xml
 * .../described_routes/users.yaml
-* .../described_routes/users.txt
 
-If the application has a route named "root", run-time-generated data will include uri_template attributes based on root_url in addition to the path_template attributes supported at build time.
+In the absence of content negotiation, requests to addresses without format extensions redirect to the respective .txt address.
+
+If the application has a route named "root", run-time-generated data will include full URIs in <code>uri_template</code> attributes based on <code>root_url</code> in addition to the <code>path_template</code> attributes supported at build time.
 
 Example:
 
@@ -165,21 +173,14 @@ JSON example (after pretty printing):
   
 === Link Generation
 
-TODO: document how to integrate described_routes_helper; meanwhile see the test_rails_app for guidance.
- 
-Generate HTML link elements by generated by adding
-
-  <%= link_elements %>
-  
-to the &lt;head&gt; part of you layout.
-
-Generate link headers (see the draft spec http://tools.ietf.org/id/draft-nottingham-http-link-header-05.txt) by including
+Generate link headers (see the draft spec http://tools.ietf.org/id/draft-nottingham-http-link-header-06.txt) by including
 
-  before_filter :set_link_header
+  include DescribedRoutes::DescribedRoutesHelper
+  after_filter :set_link_header
 
-in your controllers.  You can do this once in ApplicationController to get this behaviour across all controllers.
+in your controllers.  You can do this once in ApplicationController to get this behaviour across all controllers, or in specific controllers (for example the one for the root resource).
 
-See DescribedRoutes::DescribedRoutesHelper#link_data for configuration options.
+See DescribedRoutes::DescribedRoutesHelper#link_data for configuration options; note however that you will need to define a new filter method if you wish to override the defaults. These are set to provide the minimum information necessary to support site discovery via resource-specific metadata links.
 
 == DATA STRUCTURES and FORMATS
 

data/Rakefile

@@ -1,26 +1,27 @@
 %w[rubygems rake rake/clean fileutils newgem rubigen].each { |f| require f }
 $:.push File.dirname(__FILE__) + '/lib'
 require 'described_routes'
+require 'hoe'
 
 # Generate all the Rake tasks
 # Run 'rake -T' to see list of generated tasks (from gem root directory)
-$hoe = Hoe.new('described_routes', DescribedRoutes::VERSION) do |p|
-  p.developer('Mike Burrows', 'mjb@asplake.co.uk')
-  p.changes              = p.paragraphs_of("History.txt", 0..1).join("\n\n")
-  p.post_install_message = 'PostInstall.txt' # TODO remove if post-install message not required
-  p.rubyforge_name       = 'describedroutes'
-  p.url = 'http://positiveincline.com/?p=213'
-  p.extra_deps         = [
+$hoe = Hoe.spec 'described_routes' do
+  developer('Mike Burrows', 'mjb@asplake.co.uk')
+  self.readme_file          = "README.rdoc"
+  self.changes              = paragraphs_of("History.txt", 0..1).join("\n\n")
+  self.rubyforge_name       = 'describedroutes'
+  self.url = 'http://positiveincline.com/?p=213'
+  self.extra_deps         = [
     ['addressable','>= 2.1.0'],
   ]
-  p.extra_dev_deps = [
+  self.extra_dev_deps = [
     ['newgem', ">= #{::Newgem::VERSION}"]
   ]
   
-  p.clean_globs |= %w[**/.DS_Store tmp *.log]
-  path = (p.rubyforge_name == p.name) ? p.rubyforge_name : "\#{p.rubyforge_name}/\#{p.name}"
-  p.remote_rdoc_dir = File.join(path.gsub(/^#{p.rubyforge_name}\/?/,''), 'rdoc')
-  p.rsync_args = '-av --delete --ignore-errors'
+  self.clean_globs |= %w[**/.DS_Store tmp *.log]
+  path = (rubyforge_name == name) ? rubyforge_name : "\#{rubyforge_name}/\#{name}"
+  self.remote_rdoc_dir = File.join(path.gsub(/^#{rubyforge_name}\/?/,''), 'rdoc')
+  self.rsync_args = '-av --delete --ignore-errors'
 end
 
 task :info do

data/lib/described_routes.rb

@@ -2,5 +2,5 @@ require 'resource_template'
 
 module DescribedRoutes
   # rubygem version
-  VERSION = "0.6.1"
+  VERSION = "0.7.0"
 end

data/lib/described_routes/helpers/described_routes_helper.rb

@@ -7,12 +7,12 @@ module DescribedRoutes
     
     # The default options parameter to #link_elements; controls which links appear in html link elements 
     LINK_ELEMENT_OPTIONS = {
-      :self => true, :describedby => true, :describedby => true, :describedbywithparams => true, :up => true, :related => true
+      :self => false, :describedby => true, :up => false, :related => false
     }
     
     # The default options parameter to #link_headers; controls which links appear in html link elements 
     LINK_HEADER_OPTIONS = {
-      :self => true, :describedby => true, :describedby => true, :describedbywithparams => true, :up => true, :related => true
+      :self => false, :describedby => true, :up => false, :related => false
     }
     
     # get the resource template structure, initialised (once) from Rails routes
@@ -44,8 +44,12 @@ module DescribedRoutes
     # Render link_data as <link <url> rel=<rel> ... type=<type>> elements.  Add to the <head> part of your layout with:
     #   <%= link_elements %>
     def link_elements(options=LINK_ELEMENT_OPTIONS)
-      link_data(options).map{|url, rels, type|
-        %Q(<link href="#{url}" #{rels.map{|r| %Q(rel="#{r}")}.join(" ")} type="#{type}">)
+      link_data(options).map{|url, rels, attrs|
+        [
+          %Q(<link href="#{url}"),
+          rels.map{|r| %Q(rel="#{r}")},
+          attrs.map{|k, v| %Q(#{k}="#{v}")}
+         ].join(' ')
       }.join("\n")
     end
   
@@ -53,74 +57,81 @@ module DescribedRoutes
     #   response.headers["Link"] = link_header(options)
     # or use #set_link_header
     def link_header(options=LINK_HEADER_OPTIONS)
-      link_data(options).map{|url, rels, type|
-        %Q(<#{url}>; #{rels.map{|r| %Q(rel="#{r}")}.join("; ")}; type="#{type}")
+      link_data(options).map{|url, rels, attrs|
+        [
+          "<#{url}>",
+          rels.map{|r| %Q(rel="#{r}")},
+          attrs.map{|k, v| %Q(#{k}="#{v}")}
+         ].join('; ')
       }.join(', ')
     end
     
     # Sets a link header in the response
-    #     before_filter :set_link_header 
+    #     after_filter :set_link_header 
     def set_link_header(options=LINK_HEADER_OPTIONS)
       response.headers["Link"] = link_header(options)
     end
 
     # Returns an array of link information, each element containing 
     # 0) a URL
-    # 1) a *list* of link relation types (there can be more than one) - see explanation below
-    # 2) a "type" - actually a route name or (literally) "ResourceTemplate"
+    # 1) a list of link relation types (there can be more than one)
+    # 2) a hash of attributes, typically just one, either "role" (for regular resources) or "meta" (for metadata resources)
     # The list of link relations types will contain a standard type ('self', 'up', 'describedby') &/or an extention type
     # in the form "described_route_url(name)#rel", using the name and rel of the resource template.
     #
-    # Example output for a request to a "user" route:
-    # 
-    #   [
-    #     ['http://example.com/users/dojo', ['self'], 'user'],
-    #     ['http://example.com/users', ['up'], 'users'],
-    #     ['http://example.com/users/described_routes/user?user_id=dojo', ['describedby'], 'ResourceTemplate'],
-    #     ['http://example.com/users/dojo/edit', ['edit', 'http://example.com/user/described_routes/user#edit'], 'edit_user'],
-    #     ['http://example.com/users/dojo/edit', ['http://example.com/user/described_routes/user#profile'], 'user_profile']
-    #   ]
-    #
-    # The output is filtered by the options hash, with members :self, :describedby, :describedby, :describedbywithparams, :up, :related.
+    # The output is filtered by the options hash, with members :self, :describedby, :up, :related.
     # Rel values will include a short value (e.g. 'edit') if the template's rel has a mapping in REGISTERED_RELS. 
     #
     def link_data(options)
       result = []
       rt = resource_template
       if rt
+        type_prefix = described_routes_url + '#'
+        #
+        # For the application's root, the link with rel="describedby" has meta="ResourceTemplates" and it refers to a list of all
+        # top level resource templates. Otherwise, rel="describedby" has meta="ResourceTemplate" and it refers to a single resource
+        # template (together with any descendants).
+        #
         if rt.name == 'root'
           described_by = described_routes_url
           related = resource_templates
+          meta = "ResourceTemplates"
         else
           described_by = described_route_url(rt.name)
           related = rt.resource_templates
+          meta = "ResourceTemplate"
         end
         
+        #
+        # Add any query parameters to the rel="describedby" link
+        #
         if resource_parameters.empty?
           described_by_with_params = described_by
         else
           described_by_with_params = described_by + '?' + resource_parameters.to_query
         end
         
-        type_prefix = described_routes_url + '#'
-        
-        result << [request.url, ['self'], type_prefix + rt.name] if options[:self]
-        result << [described_by, ['describedby'], type_prefix + 'ResourceTemplate'] if options[:describedby]
-        if options[:describedbywithparams]
-          result << [described_by_with_params, ['describedby'], type_prefix + 'ResourceTemplate'] if described_by_with_params != described_by || !options[:describedby]
-        end
+        # data for rel="self"
+        result << [request.url, ['self'], {'role' => type_prefix + rt.name}] if options[:self]
+
+        # data for rel="described_by"
+        result << [described_by_with_params, ['describedby'], {'meta' => meta}] if options[:describedby]
+
+        # data for rel="up"
         if options[:up]
           if rt.parent
-            result << [rt.parent.uri_for(resource_parameters), ['up'], type_prefix + rt.parent.name]
+            result << [rt.parent.uri_for(resource_parameters), ['up'], {'role' => type_prefix + rt.parent.name}]
           elsif rt.name != 'root'
-            result << [root_url, ['up'], type_prefix + "root"]
+            result << [root_url, ['up'], {'role' => type_prefix + 'root'}]
           end
         end
+
+        # data for rel="related"
         if options[:related]
           related.expand_links(resource_parameters).map do |l|
             if l.name != rt.name
               rel = l.rel || l.name
-              result << [l.uri, REGISTERED_RELS[rel].to_a + [described_by + '#' + rel], type_prefix + l.name]
+              result << [l.uri, REGISTERED_RELS[rel].to_a + [described_by + '#' + rel], {'role' => type_prefix + l.name}]
             end
           end
         end

data/lib/described_routes/rails_controller.rb

@@ -6,6 +6,8 @@ module DescribedRoutes
   class RailsController < ActionController::Base
     include DescribedRoutes::DescribedRoutesHelper
     
+    after_filter :set_link_header
+    
     def index
       expanded_templates = resource_templates.partial_expand(request.query_parameters)
       
@@ -32,5 +34,10 @@ module DescribedRoutes
         format.xml  { render :xml  => resource_template.to_xml(Builder::XmlMarkup.new(:indent => 2)).target! }
       end
     end
+    
+    def set_link_header
+      rel = request.path == described_routes_path ? "self" : "index"
+      response.headers["Link"] = %Q(<#{described_routes_url}>; rel="#{rel}"; meta="ResourceTemplates")
+    end
   end
 end

data/test_rails_app/app/controllers/application_controller.rb

@@ -7,11 +7,18 @@ class ApplicationController < ActionController::Base
   include DescribedRoutes::DescribedRoutesHelper
   helper DescribedRoutes::DescribedRoutesHelper
 
-  before_filter :set_link_header
+  after_filter :set_link_headers
+  
   layout "default"
   
   protect_from_forgery # See ActionController::RequestForgeryProtection for details
 
   # Scrub sensitive parameters from your log
   # filter_parameter_logging :password
+  
+  protected
+  
+  def set_link_headers
+    set_link_header :self => true, :up => true, :describedby => true, :related => true
+  end
 end

data/test_rails_app/app/controllers/users_controller.rb

@@ -3,7 +3,15 @@ class UsersController < ApplicationController
     render :text => "<h1>index</h1>", :layout => true
   end
 
+  def new
+    render :text => "<h1>new</h1>", :layout => true
+  end
+
   def show
     render :text => "<h1>show #{params[:id]}</h1>", :layout => true
   end
+  
+  def edit
+    render :text => "<h1>edit #{params[:id]}</h1>", :layout => true
+  end
 end

data/test_rails_app/test/integration/headers_test.rb

@@ -4,35 +4,53 @@ class DescribedRoutesRunTimeTest < ActionController::IntegrationTest
   def test_root_headers
     get "/"
     assert_equal(
-      '<http://www.example.com/>; rel="self"; type="http://www.example.com/described_routes#root", ' +
-      '<http://www.example.com/described_routes>; rel="describedby"; type="http://www.example.com/described_routes#ResourceTemplate", ' +
-      '<http://www.example.com/admin/products>; rel="http://www.example.com/described_routes#admin_products"; type="http://www.example.com/described_routes#admin_products", ' +
-      '<http://www.example.com/described_routes>; rel="http://www.example.com/described_routes#described_routes"; type="http://www.example.com/described_routes#described_routes", ' +
-      '<http://www.example.com/pages>; rel="http://www.example.com/described_routes#pages"; type="http://www.example.com/described_routes#pages", ' +
-      '<http://www.example.com/users>; rel="http://www.example.com/described_routes#users"; type="http://www.example.com/described_routes#users"',
+      '<http://www.example.com/>; rel="self"; role="http://www.example.com/described_routes#root", ' +
+      '<http://www.example.com/described_routes>; rel="describedby"; meta="ResourceTemplates", ' +
+      '<http://www.example.com/admin/products>; rel="http://www.example.com/described_routes#admin_products"; role="http://www.example.com/described_routes#admin_products", ' +
+      '<http://www.example.com/described_routes>; rel="http://www.example.com/described_routes#described_routes"; role="http://www.example.com/described_routes#described_routes", ' +
+      '<http://www.example.com/pages>; rel="http://www.example.com/described_routes#pages"; role="http://www.example.com/described_routes#pages", ' +
+      '<http://www.example.com/users>; rel="http://www.example.com/described_routes#users"; role="http://www.example.com/described_routes#users"',
       headers["Link"])
   end
 
   def test_users_headers
     get "/users"
     assert_equal(
-      '<http://www.example.com/users>; rel="self"; type="http://www.example.com/described_routes#users", ' +
-      '<http://www.example.com/described_routes/users>; rel="describedby"; type="http://www.example.com/described_routes#ResourceTemplate", ' +
-      '<http://www.example.com/>; rel="up"; type="http://www.example.com/described_routes#root", ' +
-      '<http://www.example.com/users/new>; rel="http://www.example.com/described_routes/users#new_user"; type="http://www.example.com/described_routes#new_user"',
+      '<http://www.example.com/users>; rel="self"; role="http://www.example.com/described_routes#users", ' +
+      '<http://www.example.com/described_routes/users>; rel="describedby"; meta="ResourceTemplate", ' +
+      '<http://www.example.com/>; rel="up"; role="http://www.example.com/described_routes#root", ' +
+      '<http://www.example.com/users/new>; rel="http://www.example.com/described_routes/users#new_user"; role="http://www.example.com/described_routes#new_user"',
+      headers["Link"])
+  end
+
+  def test_new_user_headers
+    get "/users/new"
+    assert_equal(
+      '<http://www.example.com/users/new>; rel="self"; role="http://www.example.com/described_routes#new_user", ' +
+      '<http://www.example.com/described_routes/new_user>; rel="describedby"; meta="ResourceTemplate", ' +
+      '<http://www.example.com/users>; rel="up"; role="http://www.example.com/described_routes#users"',
       headers["Link"])
   end
 
   def test_user_headers
     get "/users/dojo"
     assert_equal(
-      '<http://www.example.com/users/dojo>; rel="self"; type="http://www.example.com/described_routes#user", ' +
-      '<http://www.example.com/described_routes/user>; rel="describedby"; type="http://www.example.com/described_routes#ResourceTemplate", ' +
-      '<http://www.example.com/described_routes/user?user_id=dojo>; rel="describedby"; type="http://www.example.com/described_routes#ResourceTemplate", ' +
-      '<http://www.example.com/users>; rel="up"; type="http://www.example.com/described_routes#users", ' +
-      '<http://www.example.com/users/dojo/edit>; rel="edit"; rel="http://www.example.com/described_routes/user#edit"; type="http://www.example.com/described_routes#edit_user", ' +
-      '<http://www.example.com/users/dojo/articles>; rel="http://www.example.com/described_routes/user#articles"; type="http://www.example.com/described_routes#user_articles", ' +
-      '<http://www.example.com/users/dojo/profile>; rel="http://www.example.com/described_routes/user#profile"; type="http://www.example.com/described_routes#user_profile"',
+      '<http://www.example.com/users/dojo>; rel="self"; role="http://www.example.com/described_routes#user", ' +
+      '<http://www.example.com/described_routes/user?user_id=dojo>; rel="describedby"; meta="ResourceTemplate", ' +
+      '<http://www.example.com/users>; rel="up"; role="http://www.example.com/described_routes#users", ' +
+      '<http://www.example.com/users/dojo/edit>; rel="edit"; rel="http://www.example.com/described_routes/user#edit"; role="http://www.example.com/described_routes#edit_user", ' +
+      '<http://www.example.com/users/dojo/articles>; rel="http://www.example.com/described_routes/user#articles"; role="http://www.example.com/described_routes#user_articles", ' +
+      '<http://www.example.com/users/dojo/profile>; rel="http://www.example.com/described_routes/user#profile"; role="http://www.example.com/described_routes#user_profile"',
       headers["Link"])
   end
+
+  def test_edit_user_headers
+    get "/users/dojo/edit"
+    assert_equal(
+      '<http://www.example.com/users/dojo/edit>; rel="self"; role="http://www.example.com/described_routes#edit_user", ' +
+      '<http://www.example.com/described_routes/edit_user?user_id=dojo>; rel="describedby"; meta="ResourceTemplate", ' +
+      '<http://www.example.com/users/dojo>; rel="up"; role="http://www.example.com/described_routes#user"',
+      headers["Link"])
+  end
+
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: described_routes
 version: !ruby/object:Gem::Version 
-  version: 0.6.1
+  version: 0.7.0
 platform: ruby
 authors: 
 - Mike Burrows
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-06-28 00:00:00 +01:00
+date: 2009-07-26 00:00:00 +01:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -30,7 +30,7 @@ dependencies:
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
-        version: 1.4.1
+        version: 1.5.1
     version: 
 - !ruby/object:Gem::Dependency 
   name: hoe
@@ -40,12 +40,14 @@ dependencies:
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
-        version: 1.8.0
+        version: 2.3.2
     version: 
 description: |-
-  Dynamic, framework-neutral metadata describing path/URI structures, with natural translations to/from JSON, YAML and XML.  Bonus features: easy Rails integration, link element / link header generation and a plain text report format!
-  
-  See roadmap for described_routes and path-to[http://github.com/asplake/path-to/tree] at http://positiveincline.com/?p=213.
+  Features:
+  * Dynamic, framework-neutral, client-friendly <code>ResourceTemplate</code> metadata describing the path/URI structures of your whole site or of specific resources
+  * JSON, YAML and XML formats, also a bonus plain text report
+  * A link header-based discovery protocol, enabling clients to find <code>ResourceTemplate</code> metadata from the resources of any enabled controller
+  * Easy integration with Rails
 email: 
 - mjb@asplake.co.uk
 executables: []
@@ -56,7 +58,6 @@ extra_rdoc_files:
 - History.txt
 - Manifest.txt
 - PostInstall.txt
-- README.rdoc
 files: 
 - History.txt
 - LICENSE
@@ -114,7 +115,7 @@ has_rdoc: true
 homepage: http://positiveincline.com/?p=213
 licenses: []
 
-post_install_message: PostInstall.txt
+post_install_message: 
 rdoc_options: 
 - --main
 - README.rdoc
@@ -135,10 +136,10 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 
 rubyforge_project: describedroutes
-rubygems_version: 1.3.4
+rubygems_version: 1.3.5
 signing_key: 
 specification_version: 3
-summary: Dynamic, framework-neutral metadata describing path/URI structures, with natural translations to/from JSON, YAML and XML
+summary: "Features: * Dynamic, framework-neutral, client-friendly <code>ResourceTemplate</code> metadata describing the path/URI structures of your whole site or of specific resources * JSON, YAML and XML formats, also a bonus plain text report * A link header-based discovery protocol, enabling clients to find <code>ResourceTemplate</code> metadata from the resources of any enabled controller * Easy integration with Rails"
 test_files: 
 - test/test_described_routes.rb
 - test/test_helper.rb