CatalystX::CRUD::Controller::REST(3)

NAME
CatalystX::CRUD::Controller::REST - Catalyst::Controller::REST with CRUD

SYNOPSIS
 package MyApp::Controller::Foo;
 use Moose;
 use namespace::autoclean;

 BEGIN { extends 'CatalystX::CRUD::Controller::REST' }

 __PACKAGE__->config(
    model_name      => 'Foo',
    primary_key     => 'id',
    page_size       => 50,
 );

 1;

 # now you can manage Foo objects with URIs like:
 # POST      /foo                -> create new Foo record
 # GET       /foo                -> list all Foo records
 # PUT       /foo/<pk>           -> create or update Foo record (idempotent)
 # DELETE    /foo/<pk>           -> delete Foo record
 # GET       /foo/<pk>           -> view Foo record
 # GET       /foo/<pk>/bar       -> view Bar object(s) related to Foo
 # POST      /foo/<pk>/bar       -> create Bar object related to Foo
 # GET       /foo/<pk>/bar/<pk2> -> view Bar with id <pk2> related to Foo with <pk>
 # POST      /foo/<pk>/bar/<pk2> -> create relationship between Foo <pk> and Bar <pk2>
 # DELETE    /foo/<pk>/bar/<pk2> -> sever Bar object relationship to Foo
 # PUT       /foo/<pk>/bar/<pk2> -> create/update Bar object related to Foo (idempotent)
 # GET       /foo/search         -> search for Foo objects
 # GET       /foo/count          -> search for Foo objects, returning count only

DESCRIPTION
Subclass of Catalyst::Controller::REST for use with CatalystX::CRUD.

DISCLAIMERS
This module is not to be confused with CatalystX::CRUD::REST. This is not a drop-in replacement for existing CatalystX::CRUD::Controllers.

This module extends Catalyst::Controller::REST to work with the CatalystX::CRUD::Controller API. It is designed for web services, not managing CRUD actions via HTML forms.

This is not a subclass of CatalystX::CRUD::Controller.

METHODS

  search_objects
Registers URL space for search.

  search_objects_GET
Query the model and return results. See do_search().

  count_objects
Registers URL space for count.

  count_objects_GET
Like search_objects_GET() but does not set result values, only a total count. Useful for AJAX-y types of situations where you want to query for a total number of matches and create a pager but not actually retrieve any data.

  zero_args
Registers URL space for 0 path arguments.

  zero_args_GET( ctx )
GET /foo -> list objects of type foo.

Calls do_search().

  zero_args_POST( ctx )
POST /foo -> create object of type foo.

  one_arg
Registers URL space for 1 path argument.

  one_arg_GET( ctx, pk )
GET /foo/<pk> -> retrieve object for pk.

  one_arg_PUT( ctx, pk )
PUT /foo/<pk> -> create or update the object for pk.

This method must be idempotent. POST is not.

  one_arg_DELETE( ctx, pk )
DELETE /foo/<pk> -> delete the object for pk.

  two_args
Registers URL space for 2 path arguments.

  two_args_GET( ctx, pk, rel )
GET /foo/<pk>/bar -> a list of objects of type bar related to foo.

  two_args_POST( ctx, pk, rel )
POST /foo/<pk>/bar -> create relationship between foo and bar.

TODO This method calls a not-yet-implemented create_related() action in the CXC::Model.

  three_args
Registers the URL space for 3 path arguments.

  three_args_GET( ctx, pk, rel, rel_id )
GET /foo/<pk>/<re>/<pk2>

  three_args_DELETE( ctx, pk, rel, rel_pk )
DELETE /foo/<pk>/bar/<pk2> -> sever 'bar' object relationship to 'foo'

  three_args_POST( ctx, pk, rel, rel_pk )
POST /foo/<pk>/bar/<pk2> -> create relationship between 'foo' and 'bar'

  three_args_PUT( ctx, pk, rel, rel_pk )
PUT /foo/<pk>/bar/<pk2> -> create/update 'bar' object related to 'foo'

  save_object( ctx )
Calls can_write(), inflate_object(), precommit(), create_or_update_object() and postcommit().

  create_or_update_object( ctx, object )
Calls the update() or create() method on the object (or model_adapter()), picking the method based on whether "object_id" in stash() evaluates true (update) or false (create).

  delete_object( ctx )
Checks can_write(), precommit(), and if both true, calls the delete() method on the object in the stash().

  inflate_object( ctx )
Returns the object from stash() initialized with the request data.

  can_read( ctx )
Returns true if the current request is authorized to read() the "object" in stash().

Default is true.

  can_write( ctx )
Returns true if the current request is authorized to create() or update() the "object" in stash().

Default is true.

  precommit( ctx, object )
Called by save_object(). If precommit() returns a false value, save_object() is aborted. If precommit() returns a true value, create_or_update_object() gets called.

The default return is true.

  postcommit( cxt, obj )
Called internally inside save_object(). Our default just returns true. Override this method to post-process a successful save_object() action.

  fetch( ctx, pk )
Determines the correct value and field name for pk and calls the do_model() method for "fetch".

On success, the object key will be set in stash().

On failure, calls status_not_found() and sets the fetch_failed stash() key.

  do_search( ctx, arg )
Prepare and execute a search. Called internally by list() and search().

Results are saved in stash() under the "results" key.

If naked_results is true, then results are set just as they are returned from search() or list() (directly from the Model).

If naked_results is false (default), then results is a CatalystX::CRUD::Results object.

  do_model( ctx, args )
Wrapper around the ControllerRole method of the same name. The wrapper does an eval and sets the ctx error param with $@.

AUTHOR
Peter Karman, "<karman at cpan.org>"

BUGS
Please report any bugs or feature requests to "bug-catalystx-crud-controller-rest at rt.cpan.org", or through the web interface at <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=CatalystX-CRUD-Controller-REST>. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT
You can find documentation for this module with the perldoc command.

    perldoc CatalystX::CRUD::Controller::REST

You can also look for information at:

•   Mailing List

    <https://groups.google.com/forum/#!forum/catalystxcrud>

•   RT: CPAN's request tracker

    <http://rt.cpan.org/NoAuth/Bugs.html?Dist=CatalystX-CRUD-Controller-REST>

•   AnnoCPAN: Annotated CPAN documentation

    <http://annocpan.org/dist/CatalystX-CRUD-Controller-REST>

•   CPAN Ratings

    <http://cpanratings.perl.org/d/CatalystX-CRUD-Controller-REST>

•   Search CPAN

    <http://search.cpan.org/dist/CatalystX-CRUD-Controller-REST/>

COPYRIGHT & LICENSE
Copyright 2012 Peter Karman.

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.