Picture of jgehtland

Introducing Vasco: A Route Explorer for Rails

  • Posted By Justin Gehtland on October 22, 2008

We’d like to introduce Relevance’s latest open source project, Vasco. Vasco is a route explorer for Rails projects. As we develop applications with explicit requirements for RESTful APIs for integration purposes, our clients need some way to visually accept that the stories are complete. It is also helpful for the developers to have a way to manually interact with the APIs as a second avenue for testing, verifying whether our routes end in gold and silk, or pain and death. So, we wrote Vasco.

Vasco is a simple plugin, with a single rake task. Once installed and initialized, it creates a web interface that knows about all your RESTful routes and the models at the far end of them. It lets you play with the GETs, POSTs, PUTs and DELETEs and see the responses. If your APIs are protected by BASIC auth, no worries, since the plugin runs from inside your app. And if you are lucky, it will expand your colonial footprint and lead to Empire.

To install, just run: 
> script/plugin install git://github.com/relevance/vasco.git
Once installed: 
> rake vasco:explore

After that, launch your app and point your browser to http://localhost:3000/vasco (or wherever you home your dev apps). You’ll be treated to a simple interface. On the left is a list of all the controllers in the app with RESTful routes associated with them. On the right are two boxes, one for viewing the request, one for the response. Click any controller to expand its list of available routes. If you click on something like, in this example, GET /ports, Vasco will send the request to your app and display the results immediately.

If you click on a route that requires user input, like PUT /ships/:id, a dialog will appear with a form you can fill in. The :id field will be prepopulated with a known ID from the database, assuming your database had fixture or other data loaded when you ran the vasco:explore task. You can fill in the rest of the form and either commit the request, or cancel.

After PUTting the request, the results will again be displayed. When a call only returns a status code, the results will be displayed as a simple success or failure message.

We’ve got docs on the GitHub wiki, as well as a list of upcoming features. We hope you enjoy Señor de Gama.

Comments
  1. Joachim — October 22, 2008 @ 11:24 PM

    Hi Justin,

    very good idea, highly appreciated ! My first attempt to run it failed because of a javascript error, ‘console not defined’. Once I commented that line out (59 in extension.js) everything worked fine. Before vasco I used to check my routes via the console and for sure vasco is much more agreeable :-) The ability for immidiate testing is a great plus. I hope that a future version will work with nested routes too. So thanks a lot for your work and vasco and have a good time!

    Joachim

  2. jgehtland — October 22, 2008 @ 11:58 PM

    joachim—thanks! I’ve updated the code to remove the debugging line (good ol’ Firebug). I’ll post here again when the nested routes are supported. I’ve got experimental code for it, but I need to flesh it out.

  3. Karmen Blake — October 24, 2008 @ 12:44 PM

    worked for me. neat tool. thanks!

  4. Rechnung — October 26, 2008 @ 08:39 AM

    Looks very usefull, especially when something going wrong with out app we can check what is going on.

  5. phx — October 30, 2008 @ 07:04 AM

    Hey,

    nice plugin! After the rake task i get the error: “The file data.js seems to be too large (2Mb) to safely open.”

    My IDE is Netbeans 6.5 RC1.

    greetings

  6. Andreas — November 07, 2008 @ 02:51 AM

    Using Rails 2.1.2 After sudo script/plugin install git://github.com/relevance/vasco.git and rake vasco:explore

    rake aborted! No such file or directory – .../public/vasco/js/data.js

  7. Mike Stramba — November 08, 2008 @ 04:56 PM

    ”> script/plugin install git://github.com/relevance/vasco.git”

    I get ‘sh:git command not found’

    (Red Had Linux ES release 4 (Nahant Update 7)

    - rails 2.10

    Mike

  8. Mike Stramba — November 08, 2008 @ 05:40 PM

    Ok, I figured out the missing ‘git’ ;)

    I installed git, installed vasco, ran ‘rake vasco:explore’, opened http://mstram.webfactional.com/rclog/vasco, it just says :

    Vasco

    To explore your routes, run:

    rake vasco:explore

    Format: Request

    Response

    =============

    My routes file : ActionController::Routing::Routes.draw do |map| map.resources :logs end

    1. The priority is based upon order of creation: first created -> highest priority.
    1. Sample of regular route:
    2. map.connect ‘products/:id’, :controller => ‘catalog’, :action => ‘view’
    3. Keep in mind you can assign values other than :controller and :action
    1. Sample of named route:
    2. map.purchase ‘products/:id/purchase’, :controller => ‘catalog’, :action => ‘purchase’
    3. This route can be invoked with purchase_url(:id => product.id)
    1. Sample resource route (maps HTTP verbs to controller actions automatically): map.resources :products
    1. Sample resource route with options: map.resources :products, :member => { :short => :get, :toggle => :post }, :collection => { :sold => :get }
    1. Sample resource route with sub-resources:
    2. map.resources :products, :has_many => [ :comments, :sales ], :has_one => :seller
    1. Sample resource route with more complex sub-resources
    2. map.resources :products do |products|
    3. products.resources :comments
    4. products.resources :sales, :collection => { :recent => :get }
    5. end
    1. Sample resource route within a namespace:
    2. map.namespace :admin do |admin|
    3. # Directs /admin/products/* to Admin::ProductsController (app/controllers/admin/products_controller.rb)
    4. admin.resources :products
    5. end
    1. You can have the root of your site routed with map.root—just remember to delete public/index.html.
    2. map.root :controller => “welcome”
    1. See how all your routes lay out with “rake routes”
    1. Install the default routes as the lowest priority. map.connect ’’,:controller => ‘logs’ map.connect ’:controller/:action/:id’ map.connect ’:controller/:action/:id.:format’