Home

What is RESTstop?

RESTstop is plugin for the Camping framework allowing you to create REST services.

Installation

The basic prerequisites are:

gem install rack --version '>= 1.1.0'
gem install markaby --version 0.5.0 # Note: newer versions will not work as of now (June '10)
gem install camping --version '>= 2.0'
gem install redcloth

Then install reststop:

gem install reststop

If you are planning on testing your service from IRB, I recommend the use of the restr REST client library.

gem install xml-simple
gem install restr

I also recommend the use of TcpTrace so you can intercept and inspect the HTTP traffic for your REST calls.

Running the Blog example

Note: To run this example you also need SQLite and ActiveRecord installed.

Open a command window/shell, go to restr/examples and start the blog:

camping blog.rb

You should then be able to open a browser window on the following url:

http://localhost:3301/

And the Posts page should appear without any posts. If you click on Add, you will be redirected to the login page where you can use camping as the user id and admin as the password. You should the be able to create a new Post as well as add comments.

You just tested the HTML version of the application.
The blog example supports an HTML mode and an XML mode (for REST).

Testing REST

Now let’s test the actual REST interface.

1. Open another command window/shell
   

   irb

2. Let’s load the gems
   

   gem 'xml-simple'
   gem 'restr'
   require 'restr

3. If you want to use TcpTrace to inspect the traffic, start TcpTrace now and set it up to intercept and redirect port 8080 to 3301. And in the urls below, use 8080 instead of 3301. You will then see the HTTP requests and responses!
4. Let’s define a variable to hold our credentials:
   

   o = { :username=>’admin’, :password=>’camping’ }

5. Let’s login to the service, i.e. start a session. We’ll do that by creating a Session object and doing a PUT:
   

   u0 = "http://localhost:3301/sessions.xml"
   p0=Restr.post(u0,o)

6. Let’s retrieve the first post, the one we created earlier:
   

   u = "http://localhost:3301/posts/1.xml"
   p = Restr.get(u,o)

   
   IRB should show a resulting hash of the post object converted from XML using xml-simple.
7. Now let’s modify the title slightly and issue a PUT to update the resource:
   

   p['title']=p['title']+'! :-)'
   p2=Restr.put(u,p,o)
   

   
   Now go back to the browser and refresh the post page and you should notice the updated title!

Implementing your own service

Use the blog example as your starting point and replace/adapt the Posts and Comments model to meet your needs.
A few key things to note in the example code:

1. The application module must include the following “hook” for RESTstop:
   

   include Reststop
   Controllers.extend Reststop::Controllers
   

1. The Base module needs to be created and have the following code RESTstop:
   

   alias camping_render render
     alias camping_lookup lookup	
     alias camping_service service
     include Reststop::Base
     alias service reststop_service
     alias render reststop_render
     def lookup(n)
         T.fetch(n.to_sym) do |k|
           t = Blog::Views::HTML.method_defined?(k) || camping_lookup(n)
         end
       end

1. Your Controllers module needs to have the following “hook”:
   

   extend Reststop::Controllers

1. You will add one new controller for each new REST resource

1. The Helpers module needs to include the following:
   

   alias_method :_R, :R
     remove_method :R
     include Reststop::Helpers

1. The Views module needs the following “hook”:
   

   extend Reststop::Views

1. The Views::XML module has logic to render the index and view views

So enjoy your REST at the RESTstop!
:-)