/ 
CatalystX-CRUD-Controller-REST-0.005
River stage one • 1 direct dependent • 1 total dependent
/ CatalystX::CRUD::Controller::REST

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:

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.