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
#=> '<html>...</html>'
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
#=> '<html>...</html>'
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/ <Users>
app.users(:user => 'dojo') #=> http://example.com/users/dojo <Users>
app.users[:user => 'dojo'] #=> http://example.com/users/dojo <Users>
app.articles(:user => 'dojo', :slug => 'my-article') #=> http://example.com/users/dojo/articles/my-article <Articles>
app.users[:user => 'dojo'].articles[:slug => 'my-article'] #=> http://example.com/users/dojo/articles/my-article <Articles>
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 <Articles>
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 #=> '<html>...</html>'
Installation
sudo gem install path-to
Author
Mike Burrows (asplake), email [email protected], website positiveincline.com (articles tagged path-to)