[Catalyst-commits] r8025 - in
Catalyst-Controller-DBIC-API/1.000/trunk:
lib/Catalyst/Controller/DBIC lib/Catalyst/Controller/DBIC/API t/rest
lukes at dev.catalyst.perl.org
lukes at dev.catalyst.perl.org
Sat Jun 28 14:41:38 BST 2008
Author: lukes
Date: 2008-06-28 14:41:37 +0100 (Sat, 28 Jun 2008)
New Revision: 8025
Modified:
Catalyst-Controller-DBIC-API/1.000/trunk/lib/Catalyst/Controller/DBIC/API.pm
Catalyst-Controller-DBIC-API/1.000/trunk/lib/Catalyst/Controller/DBIC/API/Base.pm
Catalyst-Controller-DBIC-API/1.000/trunk/lib/Catalyst/Controller/DBIC/API/REST.pm
Catalyst-Controller-DBIC-API/1.000/trunk/lib/Catalyst/Controller/DBIC/API/RPC.pm
Catalyst-Controller-DBIC-API/1.000/trunk/t/rest/delete.t
Catalyst-Controller-DBIC-API/1.000/trunk/t/rest/update.t
Log:
documentation complete
Modified: Catalyst-Controller-DBIC-API/1.000/trunk/lib/Catalyst/Controller/DBIC/API/Base.pm
===================================================================
--- Catalyst-Controller-DBIC-API/1.000/trunk/lib/Catalyst/Controller/DBIC/API/Base.pm 2008-06-28 12:37:13 UTC (rev 8024)
+++ Catalyst-Controller-DBIC-API/1.000/trunk/lib/Catalyst/Controller/DBIC/API/Base.pm 2008-06-28 13:41:37 UTC (rev 8025)
@@ -1,4 +1,5 @@
-package Catalyst::Controller::DBIC::API::Base;
+package # hide from PAUSE
+ Catalyst::Controller::DBIC::API::Base;
use strict;
use warnings;
@@ -19,23 +20,12 @@
rs_stash_key => 'class_rs'
);
-=head2 setup
-
-Just sets $c->stash->{$self->rs_stash_key} to the resultset specified by the 'class' config.
-This rs is then used by all other methods.
-
-=cut
-
sub setup :Chained('specify.in.subclass.config') :CaptureArgs(0) :PathPart('specify.in.subclass.config') {
my ($self, $c) = @_;
$c->stash->{$self->rs_stash_key} = $c->model($self->class);
}
-=head2 list
-
-=cut
-
sub list :Private {
my ($self, $c) = @_;
@@ -72,12 +62,6 @@
return (\%search_params, $join);
}
-=head2 list
-
-override this to customise the format of list
-
-=cut
-
sub format_list :Private {
my ($self, $c) = @_;
@@ -85,13 +69,6 @@
$c->stash->{response}->{list} = \@ret;
}
-=head2 create
-
-Matches cols specified in create_requires and create_allows to $c->req->params and $c->stash->{params}
-to create a hash representing a new object which is then created.
-
-=cut
-
sub create :Private {
my ($self, $c) = @_;
@@ -106,13 +83,6 @@
$self->validate_and_save_object($c, $empty_object);
}
-=head2 update
-
-Matches cols specified in update_allows to $c->req->params and $c->stash->{params}
-to create a hash which is used to update $c->stash->{$self->object_stash_key}
-
-=cut
-
sub update :Private {
my ($self, $c) = @_;
@@ -134,12 +104,6 @@
$self->validate_and_save_object($c, $object);
}
-=head2 delete
-
- Deletes $c->stash->{$self->object_stash_key}
-
-=cut
-
sub delete :Private {
my ($self, $c) = @_;
@@ -147,10 +111,6 @@
return $c->stash->{$self->object_stash_key}->delete;
}
-=head2 validate_and_save_object
-
-=cut
-
sub validate_and_save_object {
my ($self, $c, $object) = @_;
@@ -162,11 +122,6 @@
$self->save_object($c, $object, $params);
}
-=head2 validate
-
-=cut
-
-# rewrite this
sub validate {
my ($self, $c, $object) = @_;
my $params = $c->req->params;
@@ -238,10 +193,6 @@
return ($self->get_errors($c)) ? 0 : \%values;
}
-=head2 save_object
-
-=cut
-
sub save_object {
my ($self, $c, $object, $params) = @_;
@@ -299,7 +250,7 @@
=head1 AUTHOR
-luke saunders
+ Luke Saunders <luke.saunders at gmail.com>
=cut
Modified: Catalyst-Controller-DBIC-API/1.000/trunk/lib/Catalyst/Controller/DBIC/API/REST.pm
===================================================================
--- Catalyst-Controller-DBIC-API/1.000/trunk/lib/Catalyst/Controller/DBIC/API/REST.pm 2008-06-28 12:37:13 UTC (rev 8024)
+++ Catalyst-Controller-DBIC-API/1.000/trunk/lib/Catalyst/Controller/DBIC/API/REST.pm 2008-06-28 13:41:37 UTC (rev 8025)
@@ -5,34 +5,66 @@
use base qw/Catalyst::Controller::DBIC::API::Base/;
__PACKAGE__->config(
- 'default' => 'text/x-json',
+ 'default' => 'application/json',
'stash_key' => 'response',
'map' => {
- 'text/x-json' => 'JSON',
+ 'application/x-www-form-urlencoded' => 'JSON',
+ 'application/json' => 'JSON',
});
=head1 NAME
-Catalyst::Controller::REST::DBIC
+Catalyst::Controller::DBIC::API::REST
-=head1 SYNOPSIS
+=head1 DESCRIPTION
- package MyApp::Controller::REST::CD;
+Provides a REST style API interface to the functionality described in L<Catalyst::Controller::DBIC::API>.
- use base qw/Catalyst::Controller::REST::DBIC/;
+By default provides the following endpoints:
- ...
+ $base (accepts PUT and GET)
+ $base/[identifier] (accepts POST and DELETE)
- __PACKAGE__->config
- ( action => { setup => { PathPart => 'cd', Chained => '/api/rest/rest_base' } },
- class => 'TestDB::CD',
- create_requires => ['artist', 'title', 'year' ],
- update_allows => ['title', 'year']
- );
+Where $base is the URI described by L</setup>, the chain root of the controller, and the request type will determine the L<Catalyst::Controller::DBIC::API> method to forward.
=head1 METHODS
-=head2 end
+=head2 setup
+Chained: override
+PathPart: override
+CaptureArgs: 0
+
+As described in L<Catalyst::Controller::DBIC::API/setup>, this action is the chain root of the controller but has no pathpart or chain parent defined by default, so these must be defined in order for the controller to function. The neatest way is normally to define these using the controller's config.
+
+ __PACKAGE__->config
+ ( action => { setup => { PathPart => 'track', Chained => '/api/rest/rest_base' } },
+ ...
+ );
+
+=head2 base
+
+Chained: L</setup>
+PathPart: none
+CaptureArgs: 0
+
+Forwards to list level methods described in L<Catalyst::Controller::DBIC::API> as follows:
+
+POST: forwards to L<Catalyst::Controller::DBIC::API/create>
+GET: forwards to L<Catalyst::Controller::DBIC::API/list>
+
+=head2 object
+
+Chained: L</setup>
+PathPart: none
+CaptureArgs: 1
+
+Forwards to object level methods described in L<Catalyst::Controller::DBIC::API> as follows:
+
+DELETE: forwards to L<Catalyst::Controller::DBIC::API/delete>
+PUT: forwards to L<Catalyst::Controller::DBIC::API/update>
+
+Note: It is often sensible although controversial to give this method a PathPart to clearly distinguish between object and list level methods. You can easily do this by using the controller config as with L</setup>.
+
=cut
sub begin :Private {
@@ -49,7 +81,7 @@
}
-sub object :Chained('setup') :Args(1) :PathPart('id') :ActionClass('REST') {
+sub object :Chained('setup') :Args(1) :PathPart('') :ActionClass('REST') {
my ($self, $c, $id) = @_;
my $object = $c->stash->{$self->rs_stash_key}->find( $id );
@@ -103,7 +135,7 @@
=head1 AUTHOR
-luke saunders
+ Luke Saunders <luke.saunders at gmail.com>
=cut
Modified: Catalyst-Controller-DBIC-API/1.000/trunk/lib/Catalyst/Controller/DBIC/API/RPC.pm
===================================================================
--- Catalyst-Controller-DBIC-API/1.000/trunk/lib/Catalyst/Controller/DBIC/API/RPC.pm 2008-06-28 12:37:13 UTC (rev 8024)
+++ Catalyst-Controller-DBIC-API/1.000/trunk/lib/Catalyst/Controller/DBIC/API/RPC.pm 2008-06-28 13:41:37 UTC (rev 8025)
@@ -14,35 +14,78 @@
});
=head1 NAME
-Catalyst::Controller::RPC::DBIC
+Catalyst::Controller::DBIC::API::RPC
-=head1 SYNOPSIS
+=head1 DESCRIPTION
- package MyApp::Controller::RPC::CD;
+Provides an RPC API interface to the functionality described in L<Catalyst::Controller::DBIC::API>.
- use base qw/Catalyst::Controller::RPC::DBIC/;
+By default provides the following endpoints:
- ...
+ $base/create
+ $base/list
+ $base/id/[identified]/delete
+ $base/id/[identified]/update
- __PACKAGE__->config
- ( action => { setup => { PathPart => 'cd', Chained => '/api/rpc/rest_base' } },
- class => 'TestDB::CD',
- create_requires => ['artist', 'title', 'year' ],
- update_allows => ['title', 'year']
- );
+Where $base is the URI described by L</setup>, the chain root of the controller.
=head1 METHODS
-=head2 end
+=head2 setup
-=cut
+Chained: override
+PathPart: override
+CaptureArgs: 0
+As described in L<Catalyst::Controller::DBIC::API/setup>, this action is the chain root of the controller but has no pathpart or chain parent defined by default, so these must be defined in order for the controller to function. The neatest way is normally to define these using the controller's config.
+
+ __PACKAGE__->config
+ ( action => { setup => { PathPart => 'track', Chained => '/api/rpc/rpc_base' } },
+ ...
+ );
+
=head2 object
-Sets the object that is used by update, delete etc which chain from this.
+Chained: L</setup>
+PathPart: object
+CaptureArgs: 1
-=cut
+Provides an endpoint to the functionality described in L<Catalyst::Controller::DBIC::API/object>.
+=head2 create
+
+Chained: L</setup>
+PathPart: create
+CaptureArgs: 0
+
+Provides an endpoint to the functionality described in L<Catalyst::Controller::DBIC::API/create>.
+
+=head2 list
+
+Chained: L</setup>
+PathPart: list
+CaptureArgs: 0
+
+Provides an endpoint to the functionality described in L<Catalyst::Controller::DBIC::API/list>.
+
+=head2 delete
+
+Chained: L</object>
+PathPart: delete
+CaptureArgs: 0
+
+Provides an endpoint to the functionality described in L<Catalyst::Controller::DBIC::API/delete>.
+
+=head2 update
+
+Chained: L</object>
+PathPart: update
+CaptureArgs: 0
+
+Provides an endpoint to the functionality described in L<Catalyst::Controller::DBIC::API/update>.
+
+=cut
+
sub object :Chained('setup') :CaptureArgs(1) :PathPart('id') {
my ($self, $c, $id) = @_;
@@ -61,115 +104,33 @@
$c->res->status( '404' );
}
-=head2 create
-
-Matches cols specified in create_requires and create_allows to $c->req->params and $c->stash->{params}
-to create a hash representing a new object which is then created.
-
-=cut
-
sub create :Chained('setup') :PathPart('create') :Args(0) {
my ($self, $c) = @_;
$self->NEXT::create($c);
}
-=head2 list
-
-Returns a list of objects from the class resultset. The columns to be returned can be specified
-
-=cut
-
sub list :Chained('setup') :PathPart('list') :Args(0) {
my ($self, $c) = @_;
$self->NEXT::list($c);
}
-=head2 update
-
-Matches cols specified in update_allows to $c->req->params and $c->stash->{params}
-to create a hash which is used to update $c->stash->{$self->object_stash_key}
-
-=cut
-
sub update :Chained('object') :PathPart('update') :Args(0) {
my ($self, $c) = @_;
$self->NEXT::update($c);
}
-=head2 delete
-
- Deletes $c->stash->{$self->object_stash_key}
-
-=cut
-
sub delete :Chained('object') :PathPart('delete') :Args(0) {
my ($self, $c) = @_;
$self->NEXT::delete($c);
}
-# =head2 add_to_rel
-
-# finds a related row and then creates the many_to_many linking row using ->add_to_$rel
-# This is a work in progress, it should really allow the related row to also be created
-# if it does not already exist.
-
-# =cut
-
-# sub add_to_rel : Chained('object') PathPart('add_to_rel') Args(1) {
-# my ($self, $c, $rel) = @_;
-
-# my $accessor = "add_to_$rel";
-# $self->__rel($c, $rel, $accessor);
-# }
-
-# =head2 remove_from_rel
-
-# finds a related row and then removes the many_to_many linking row using ->remove_from_$rel
-
-# =cut
-
-# sub remove_from_rel : Chained('object') PathPart('remove_from_rel') Args(1) {
-# my ($self, $c, $rel) = @_;
-
-# my $accessor = "remove_from_$rel";
-# $self->__rel($c, $rel, $accessor);
-# }
-
-# sub __rel {
-# my ($self, $c, $rel, $accessor) = @_;
-
-# my $related_rs;
-# # pretty grim but i want it to work for many_to_many as well (so not $source->has_relationship)
-# eval {
-# $related_rs = $c->stash->{$self->object_stash_key}->$rel;
-# };
-# if ($@) {
-# $c->detach( 'error', [{ message => "Invalid relationship $rel" }]);
-# }
-# my $source = $related_rs->result_source;
-
-# my %related_args = map { $_ => $c->req->params->{$_} } grep { $c->req->params->{$_} } $source->columns;
-
-# unless (keys %related_args) {
-# $c->detach( 'error', [{ message => "No valid keys passed" }]);
-# }
-
-# my $related_row = $related_rs->result_source->resultset->find(\%related_args);
-# unless ($related_row) {
-# $c->detach( 'error', [{ message => "Invalid related row" }]);
-# }
-
-# $c->stash->{$self->object_stash_key}->$accessor($related_row);
-# }
-
-
=head1 AUTHOR
-luke saunders
+ Luke Saunders <luke.saunders at gmail.com>
=cut
Modified: Catalyst-Controller-DBIC-API/1.000/trunk/lib/Catalyst/Controller/DBIC/API.pm
===================================================================
--- Catalyst-Controller-DBIC-API/1.000/trunk/lib/Catalyst/Controller/DBIC/API.pm 2008-06-28 12:37:13 UTC (rev 8024)
+++ Catalyst-Controller-DBIC-API/1.000/trunk/lib/Catalyst/Controller/DBIC/API.pm 2008-06-28 13:41:37 UTC (rev 8025)
@@ -40,10 +40,12 @@
=head1 GETTING STARTED
-See L<Catalyst::Controller::API::Base> for descriptions of base functionlity such as list, create, delete, update and config attributes. Then see L<Catalyst::Controller::API::RPC> or L<Catalyst::Controller::API::REST> for details of provided endpoints to those base methods.
+This document describes base functionlity such as list, create, delete, update and the setting of config attributes. L<Catalyst::Controller::API::RPC> and L<Catalyst::Controller::API::REST> describe details of provided endpoints to those base methods.
-You will need to create a controller for each schema class you need endpoints for. For example if your schema has Artist and Track, and you want to provide a RESTful interface to these, you should create MyApp::Controller::API::REST::Artist and MyApp::Controller::API::REST::Track. You then configure these individually as specified in L</CONFIGURATION>.
+You will need to create a controller for each schema class you require API endpoints for. For example if your schema has Artist and Track, and you want to provide a RESTful interface to these, you should create MyApp::Controller::API::REST::Artist and MyApp::Controller::API::REST::Track which both subclass L<Catalyst::Controller::API::REST>. Similarly if you wanted to provide an RPC style interface then subclass L<Catalyst::Controller::API::RPC>. You then configure these individually as specified in L</CONFIGURATION>.
+Also note that the test suite of this module has an example application used to run tests against. It maybe helpful to look at that until a better tutorial is written.
+
=head2 CONFIGURATION
Each of your controller classes needs to be configured to point at the relevant schema class, specify what can be updated and so on, as shown in the L</SYNOPSIS>.
@@ -102,7 +104,7 @@
=head2 object
-This action is the chain root for all object level actions (such as delete and update)
+This action is the chain root for all object level actions (such as delete and update). Takes one argument which is passed to L<DBIx::Class::ResultSet/find>, if an object is returned then it is set in $c->stash->{$self->object_stash_key}.
=head2 create
@@ -155,8 +157,8 @@
=head1 AUTHOR
- Luke Saunders <luke.saunders at gmail.com>
-
+ Luke Saunders <luke.saunders at gmail.com
+>
=head1 CONTRIBUTORS
Zbigniew Lukasiak <zzbbyy at gmail.com>
Modified: Catalyst-Controller-DBIC-API/1.000/trunk/t/rest/delete.t
===================================================================
--- Catalyst-Controller-DBIC-API/1.000/trunk/t/rest/delete.t 2008-06-28 12:37:13 UTC (rev 8024)
+++ Catalyst-Controller-DBIC-API/1.000/trunk/t/rest/delete.t 2008-06-28 13:41:37 UTC (rev 8025)
@@ -21,7 +21,7 @@
my $track = $schema->resultset('Track')->first;
my %original_cols = $track->get_columns;
-my $track_delete_url = "$base/api/rest/track/id/" . $track->id;
+my $track_delete_url = "$base/api/rest/track/" . $track->id;
{
my $req = HTTP::Request->new( DELETE => $track_delete_url );
Modified: Catalyst-Controller-DBIC-API/1.000/trunk/t/rest/update.t
===================================================================
--- Catalyst-Controller-DBIC-API/1.000/trunk/t/rest/update.t 2008-06-28 12:37:13 UTC (rev 8024)
+++ Catalyst-Controller-DBIC-API/1.000/trunk/t/rest/update.t 2008-06-28 13:41:37 UTC (rev 8025)
@@ -21,12 +21,12 @@
my $track = $schema->resultset('Track')->first;
my %original_cols = $track->get_columns;
-my $track_update_url = "$base/api/rest/track/id/" . $track->id;
+my $track_update_url = "$base/api/rest/track/" . $track->id;
# test invalid track id caught
{
foreach my $wrong_id ('sdsdsdsd', 3434234) {
- my $incorrect_url = "$base/api/rest/track/id/" . $wrong_id;
+ my $incorrect_url = "$base/api/rest/track/" . $wrong_id;
my $test_data = JSON::Syck::Dump({ title => 'value' });
my $req = POST( $incorrect_url, Content => $test_data );
$req->content_type('text/x-json');
More information about the Catalyst-commits
mailing list