Webmachine for Ruby

Julian Doherty

@madlep

We like Rest

Consistent
Predictable
Grokable
Scalable
Developer Friendly

DISCLAIMER

I'm gonna be that guy in a minute

REST > CRUD

REST?

class BlearghController < ActionController::Base
  def index
  end

  def new
  end

  def create
  end

  def show
  end

  def edit
  end

  def update
  end

  def destroy
  end
end

Yes, but REST does more

Wrapping REST around MVC is a leaky abstraction

REST =~ HTTP

To get REST right, you need to get HTTP right

authentication; content type negotiation; caching; redirects; language; http verbs; status codes...

So let's build REST/HTTP apps shaped around HTTP

Doing HTTP properly is hard

Actually, doing HTTP "just ok" isn't too hard

But doing HTTP properly is HARD

So... do I return a 201 Created... Or a 409 Conflict... or 417 Expectation Failed?... What if the client accepts JSON but has a character set I don't know about?... What if I don't implement that method on that resource?... What if caching headers don't match?... What if the resource doesn't exist, but it's being updated?... Or what about...

Enter Webmachine

Original written in Erlang. Still going strong

Talking about Ruby port today

HTTP protocol is FSM

So let's just define functions to handle the decision points

resource_exists? service_available? is_authorized? forbidden? allow_missing_post? malformed_request? uri_too_long? known_content_type? valid_content_headers? valid_entity_length? options allowed_methods known_methods delete_resource delete_completed? post_is_create? create_path base_uri process_post content_types_provided content_types_accepted charsets_provided languages_provided language_chosen encodings_provided variances is_conflict? multiple_choices? previously_existed? moved_permanently? moved_temporarily? last_modified expires generate_etag finish_request handle_exception validate_content_checksum

Fill in the blanks. Webmachine takes care of playing nice with HTTP for you

class BlearghPostResource < Webmachine::Resource
  def service_available?
    DB.connected?
  end

  def allowed_methods
    %w{GET POST PUT DELETE HEAD}
  end

  def resource_exist?
    @bleargh_post = BlearghPost.find(request.path_info(:post_id))
    !@bleargh_post.nil?
  end

  ...

end

Some code

https://github.com/madlep/webmachine_ruby_shortener

When could you use Webmachine?

Building a REST API
Using multiple (human) languages
Serving up multiple content types
Doing more than just CRUD
Fat JS client talking JSON over AJAX to the server
You know and care what HATEOAS means

Why wouldn't you use it?

Traditional site. DB → Model → Controller → HTML (use Rails)
Something super simple (use Sinatra)
Websockets/long polling/comet. Explictly designed for req/response HTTP
You use lots of Rack middleware

Cheers