NAME

Wurm::Grub::REST - Wurm::let grub for generating RESTful services.

SYNOPSIS

use Wurm qw(mob let);
use Wurm::Grub::REST;
use Data::UUID;
use JSON::XS;
use Tenjin;

my $grub = Wurm::Grub::REST->new
->get(
  sub {
    my $meal = shift;

    my $item = $meal->mind->{meld}{$meal->grit->{id}};
    return
      unless defined $item;

    $meal->grit->{item} = $item;
    return $meal->vent->{json}
      ? to_json($meal)
      : to_html($meal, 'item.html')
    ;
  },
  sub {
    my $meal = shift;

    $meal->grit->{items} = $meal->mind->{meld};
    return $meal->vent->{json}
      ? to_json($meal)
      : to_html($meal, 'index.html')
    ;
  },
)
->post(sub {
  my $meal = shift;

  my $text = $meal->req->parameters->{text};
  return
    unless defined $text;

  $meal->grit->{id} = gen_uuid($meal);
  $meal->mind->{meld}{$meal->grit->{id}} = $text;
  return Wurm::_302($meal->env->{PATH_INFO});
})
->patch(sub {
  my $meal = shift;

  return
    unless exists $meal->mind->{meld}{$meal->grit->{id}};

  my $text = $meal->req->parameters->{text};
  return
    unless defined $text;

  $meal->mind->{meld}{$meal->grit->{id}} = $text;
  return Wurm::_204;
})
->delete(sub {
  my $meal = shift;

  return
    unless exists $meal->mind->{meld}{$meal->grit->{id}};

  delete $meal->mind->{meld}{$meal->grit->{id}};
  return Wurm::_204;
})
;

sub gen_uuid {
  my $meal = shift;
  my $uuid = $meal->mind->{uuid};
  return lc $uuid->to_string($uuid->create);
}

sub to_html {
  my $meal = shift;
  my $file = shift;
  my $html = $meal->mind->{html}->render($file, $meal->grit);
  return Wurm::_200('text/html', $html);
}

sub to_json {
  my $meal = shift;
  my $json = $meal->mind->{json}->encode($meal->grit);
  return Wurm::_200('application/json', $json);
}

my $mind = {
  meld => {'Wurm::Grub::REST' => 'Hello, Wurm!'},
  uuid => Data::UUID->new,
  json => JSON::XS->new->utf8,
  html => Tenjin->new({
    path => ['./examples/html/rest'], strict => 1, cache => 0
  }),
};

my $app = Wurm::wrapp($grub->molt, $mind);
$app

DESCRIPTION

Wurm::Grub::REST is a Wurm::let to help build REST-enabled services. It provides a library of light-weight handler wrappers that attempt to conform to the REST protocol specification.

METHODS

Please see the documentation for Wurm::let for a description of super-class methods. Below is a list of overriden methods:

new($accept_map)

Creates a new Wurm::let object with a gate handler installed that will inspect the HTTP_ACCEPT request variable for possible response content types. The $accept_map parameter can be used to specify a custom mapping between a mime-type and a key name that will be set in $meal->{vent}. If no map is given, a default map is installed with the following values:

text/html        => html
application/json => json
text/xml         => xml
application/xml  => xml

The purpose of this is to make response encoding decisions easier. When the HTTP Accept header is set properly, this should allow you to do something like:

sub handler {
  my $meal = shift;

  ...

  if   ($meal->{vent}{json}) { return to_json($meal); }
  elsif($meal->{vent}{xml} ) { return to_xml ($meal); }
  elsif($meal->{vent}{html}) { return to_html($meal); }

  # no type handler installed; someone else's problem
  return;
}

The gate handler will also modify $meal->{tube} by calling Wurm::bend() assuming that any atom returned is an application record id. This is stored in $meal->{grit}{id} for further down-stream dispatching and access to the application. From the client point-of-view, this simply looks like:

'http://.../path/to/rest'

and

'http://.../path/to/rest/$id'

get($one, $all)

Adds an HTTP GET body handler to implement record and collection indexing and retrieval.

If a record id is present, the $one handler is called. Otherwise the $all handler is called. Each are expected to return a response upon success. If no response is returned, an HTTP 404 is returned instead.

post($post)

Adds an HTTP POST body handler to implement record creation.

If a record id is present, an HTTP 400 is generated. Otherwise the request is dispatched to the handler in $post which may return its own response. If no response is returned an HTTP 400 will be generated if $meal->{grit}{id} is not defined. Otherwise an HTTP <201> will be generated with the Location header set to the URL of the new resource.

put($old, $new)

Adds an HTTP PUT body handler to implement record modification and creation.

If a record id is present, the $old hander is called. Otherwise the $new handler is called. Each are expected to return a response upon success. If no record id is present in $meal->{grit}{id} after calling the handler, an HTTP 400 response is returned. Otherwise a redirect to the resource URL will be generated with the code set to 201 for new records and 302 for old records.

patch($one, $all)

Adds an HTTP PATCH body handler to implement record and collection patching.

If a record id is present, the $one handler is called and is expected to generate a response upon success. An HTTP 400 will be generated if the record id is removed from $meal->{grit}{id}. An HTTP 404 is generated if the handler does not generate a response.

If no record id is present, an HTTP 404 will be returned if the handler in $all is not defined. If a handler is defined, it will be called expecting to return a response. If no response is returned an HTTP 400 is generated.

delete($delete)

Adds an HTTP DELETE body handler to implement record and collection deletion.

If a record id is present, the $one handler is called and is expected to generate a response upon success. An HTTP 400 will be generated if the record id is removed from $meal->{grit}{id}. An HTTP 404 is generated if the handler does not generate a response.

If no record id is present, an HTTP 404 will be returned if the handler in $all is not defined. If a handler is defined, it will be called expecting to return a response. If no response is returned an HTTP 400 is generated.

SEE ALSO

Wurm

Wurm::let

AUTHOR

jason hord <pravus@cpan.org>

LICENSE

This software is information. It is subject only to local laws of physics.