path-to

= path-to README

Model web apps easily and access them via nice app-specific Ruby APIs on the client side. For suitably-configured servers (e.g. those using described_routes), path-to applications can bootstrap themselves from the address of any resource in the target application.

== Synopsis

=== Automatic configuration with described_routes

Create a client application for a web app that supports the described_routes discovery protocol:

require 'path-to/described_routes' app = PathTo::DescribedRoutes::Application.discover('http://example.com')

Or create one from a ResourceTemplate description in JSON or YAML found at some known place, preferable on the server. This could be generated and served by the Rails controller provided by described_routes or perhaps hand-crafted and configured statically:

require 'path-to/described_routes' app = PathTo::DescribedRoutes::Application.new(:json => Net::HTTP.get(URI.parse('http://example.com/described_routes.json')))

The app object then automatically supports an API that reflects the structure of the web application, for example:

app.users['dojo'].articles.recent #=> http://example.com/users/dojo/articles/recent app.users['dojo'].articles.recent.get #=> '...'

app.users['dojo'].articles.recent['format' => 'json'] #=> http://example.com/users/dojo/articles/recent.json app.users['dojo'].articles.recent.get #=> [...]

The API objects include the #get, #put, #post and #delete of HTTParty (or other HTTP client provided at initialization). Alternatively you can use their #uri or #path methods with an un-integrated HTTP client:

your_favourite_http_client.get app.users['dojo'].articles.recent.uri #=> '...'

=== Local configuration - using path-to without described_routes

require 'path-to'

class Users < PathTo::Path ; end class Articles < PathTo::Path ; end

app = Application.new( :users => 'http://example.com/users/{user}', :articles => 'http://example.com/users/{user}/articles/{slug}') do |app| def app.child_class_for(instance, method, params) { :users => Users, :articles => Articles }[method] end end #=> Application

Note that the Users and Articles classes and the overridden #child_class_for method above can be done away with (reducing the above code to just four lines) if there is no need to define any class-specific behaviour.

Having defined URI template and class mappings for keys :users and :articles mapping to URI templates, calls to app.users and app.articles cause objects of the appropriate class to be generated. These in turn support chaining and the collection of request params, like this:

app.users #=> http://example.com/users/ app.users(:user => 'dojo') #=> http://example.com/users/dojo app.users[:user => 'dojo'] #=> http://example.com/users/dojo app.articles(:user => 'dojo', :slug => 'my-article') #=> http://example.com/users/dojo/articles/my-article app.users[:user => 'dojo'].articles[:slug => 'my-article'] #=> http://example.com/users/dojo/articles/my-article

With a little more work (overriding Users#[] and Articles#[] - as described in the documentation for the Path class), the last example becomes simply:

app.users['dojo'].articles['my-article'] #=> http://example.com/users/dojo/articles/my-article

HTTP support comes courtesy of HTTParty (the Path class includes it). To GET an article in the above example, just invoke the get method on the path object:

app.users['dojo'].articles['my-article'].get #=> '...'

== Installation

sudo gem install path-to

== Author

Mike Burrows (asplake), email mailto:[e-mail], website positiveincline.com[http://positiveincline.com] (articles tagged path-to[http://positiveincline.com/?tag=path-to])