1 package Catalyst::Controller::DBIC::API;
3 #ABSTRACT: Provides a DBIx::Class web service automagically
5 BEGIN { extends 'Catalyst::Controller'; }
8 use DBIx::Class::ResultClass::HashRefInflator;
10 use Test::Deep::NoTest('eq_deeply');
11 use MooseX::Types::Moose(':all');
13 use Scalar::Util( 'blessed', 'reftype' );
15 use Catalyst::Controller::DBIC::API::Request;
16 use namespace::autoclean;
26 # no ->utf8 here because the request params get decoded by Catalyst
30 with 'Catalyst::Controller::DBIC::API::StoredResultSource',
31 'Catalyst::Controller::DBIC::API::StaticArguments';
33 with 'Catalyst::Controller::DBIC::API::RequestArguments' => { static => 1 };
35 __PACKAGE__->config();
39 package MyApp::Controller::API::RPC::Artist;
41 BEGIN { extends 'Catalyst::Controller::DBIC::API::RPC' }
44 ( # define parent chain action and PathPart
47 Chained => '/api/rpc/rpc_base',
51 class => 'MyAppDB::Artist',
52 resultset_class => 'MyAppDB::ResultSet::Artist',
53 create_requires => ['name', 'age'],
54 create_allows => ['nickname'],
55 update_allows => ['name', 'age', 'nickname'],
56 update_allows => ['name', 'age', 'nickname'],
57 select => ['name', 'age'],
62 { cds => ['tracks'] },
64 ordered_by => ['age'],
65 search_exposes => ['age', 'nickname', { cds => ['title', 'year'] }],
67 use_json_boolean => 1,
71 # Provides the following functional endpoints:
72 # /api/rpc/artist/create
73 # /api/rpc/artist/list
74 # /api/rpc/artist/id/[id]/delete
75 # /api/rpc/artist/id/[id]/update
82 begin is provided in the base class to setup the Catalyst Request object, by applying the DBIC::API::Request role.
87 my ( $self, $c ) = @_;
89 Moose::Util::ensure_all_roles( $c->req,
90 'Catalyst::Controller::DBIC::API::Request' );
93 =method_protected setup
95 :Chained('specify.in.subclass.config') :CaptureArgs(0) :PathPart('specify.in.subclass.config')
97 This action is the chain root of the controller. It must either be overridden or
98 configured to provide a base PathPart to the action and also a parent action.
99 For example, for class MyAppDB::Track you might have
101 package MyApp::Controller::API::RPC::Track;
103 BEGIN { extends 'Catalyst::Controller::DBIC::API::RPC'; }
106 ( action => { setup => { PathPart => 'track', Chained => '/api/rpc/rpc_base' } },
112 sub setup :Chained('/api/rpc/rpc_base') :CaptureArgs(0) :PathPart('track') {
115 $self->next::method($c);
118 This action does nothing by default.
122 sub setup : Chained('specify.in.subclass.config') : CaptureArgs(0) :
123 PathPart('specify.in.subclass.config') { }
125 =method_protected deserialize
127 :Chained('setup') :CaptureArgs(0) :PathPart('') :ActionClass('Deserialize')
129 deserialize absorbs the request data and transforms it into useful bits by using CGI::Expand->expand_hash and a smattering of JSON->decode for a handful of arguments. Current only the following arguments are capable of being expressed as JSON:
138 It should be noted that arguments can used mixed modes in with some caveats. Each top level arg can be expressed as CGI::Expand with their immediate child keys expressed as JSON when sending the data application/x-www-form-urlencoded. Otherwise, you can send content as raw json and it will be deserialized as is with no CGI::Expand expasion.
142 sub deserialize : Chained('setup') : CaptureArgs(0) : PathPart('') :
143 ActionClass('Deserialize') {
144 my ( $self, $c ) = @_;
147 if ( $c->req->data && scalar( keys %{ $c->req->data } ) ) {
148 $req_params = $c->req->data;
151 $req_params = CGI::Expand->expand_hash( $c->req->params );
154 @{ [ $self->search_arg, $self->count_arg,
155 $self->page_arg, $self->offset_arg,
156 $self->ordered_by_arg, $self->grouped_by_arg,
162 # these params can also be composed of JSON
163 # but skip if the parameter is not provided
164 next if not exists $req_params->{$param};
166 # find out if CGI::Expand was involved
167 if ( ref $req_params->{$param} eq 'HASH' ) {
168 for my $key ( keys %{ $req_params->{$param} } ) {
170 # copy the value because JSON::XS will alter it
171 # even if decoding failed
172 my $value = $req_params->{$param}->{$key};
174 my $deserialized = $self->_json->decode($value);
175 $req_params->{$param}->{$key} = $deserialized;
179 "Param '$param.$key' did not deserialize appropriately: $_"
186 my $value = $req_params->{$param};
187 my $deserialized = $self->_json->decode($value);
188 $req_params->{$param} = $deserialized;
192 "Param '$param' did not deserialize appropriately: $_"
199 $self->inflate_request( $c, $req_params );
202 =method_protected generate_rs
204 generate_rs is used by inflate_request to get a resultset for the current
205 request. It receives $c as its only argument.
206 By default it returns a resultset of the controller's class.
207 Override this method if you need to manipulate the default implementation of
213 my ( $self, $c ) = @_;
215 return $c->model( $c->stash->{class} || $self->class );
218 =method_protected inflate_request
220 inflate_request is called at the end of deserialize to populate key portions of the request with the useful bits
224 sub inflate_request {
225 my ( $self, $c, $params ) = @_;
228 # set static arguments
229 $c->req->_set_controller($self);
231 # set request arguments
232 $c->req->_set_request_data($params);
234 # set the current resultset
235 $c->req->_set_current_result_set( $self->generate_rs($c) );
240 $self->push_error( $c, { message => $_ } );
245 =method_protected object_with_id
247 :Chained('deserialize') :CaptureArgs(1) :PathPart('')
249 This action is the chain root for all object level actions (such as delete and update) that operate on a single identifer. The provided identifier will be used to find that particular object and add it to the request's store of objects. Please see L<Catalyst::Controller::DBIC::API::Context> for more details on the stored objects.
253 sub object_with_id : Chained('deserialize') : CaptureArgs(1) : PathPart('') {
254 my ( $self, $c, $id ) = @_;
256 my $vals = $c->req->request_data->{ $self->data_root };
257 unless ( defined($vals) ) {
259 # no data root, assume the request_data itself is the payload
260 $vals = $c->req->request_data;
264 # there can be only one set of data
265 $c->req->add_object( [ $self->object_lookup( $c, $id ), $vals ] );
269 $self->push_error( $c, { message => $_ } );
274 =method_protected objects_no_id
276 :Chained('deserialize') :CaptureArgs(0) :PathPart('')
278 This action is the chain root for object level actions (such as create, update, or delete) that can involve more than one object. The data stored at the data_root of the request_data will be interpreted as an array of hashes on which to operate. If the hashes are missing an 'id' key, they will be considered a new object to be created. Otherwise, the values in the hash will be used to perform an update. As a special case, a single hash sent will be coerced into an array. Please see L<Catalyst::Controller::DBIC::API::Context> for more details on the stored objects.
282 sub objects_no_id : Chained('deserialize') : CaptureArgs(0) : PathPart('') {
283 my ( $self, $c ) = @_;
285 if ( $c->req->has_request_data ) {
286 my $data = $c->req->request_data;
289 if ( exists( $data->{ $self->data_root } )
290 && defined( $data->{ $self->data_root } ) )
292 my $root = $data->{ $self->data_root };
293 if ( reftype($root) eq 'ARRAY' ) {
296 elsif ( reftype($root) eq 'HASH' ) {
300 $c->log->error('Invalid request data');
301 $self->push_error( $c,
302 { message => 'Invalid request data' } );
307 # no data root, assume the request_data itself is the payload
308 $vals = [ $c->req->request_data ];
311 foreach my $val (@$vals) {
312 unless ( exists( $val->{id} ) ) {
314 [ $c->req->current_result_set->new_result( {} ), $val ] );
320 [ $self->object_lookup( $c, $val->{id} ), $val ] );
324 $self->push_error( $c, { message => $_ } );
331 =method_protected object_lookup
333 This method provides the look up functionality for an object based on 'id'. It is passed the current $c and the $id to be used to perform the lookup. Dies if there is no provided $id or if no object was found.
338 my ( $self, $c, $id ) = @_;
340 die 'No valid ID provided for look up' unless defined $id and length $id;
341 my $object = $c->req->current_result_set->find($id);
342 die "No object found for id '$id'" unless defined $object;
346 =method_protected list
348 list's steps are broken up into three distinct methods: L</list_munge_parameters>, L</list_perform_search>, and L</list_format_output>.
350 The goal of this method is to call ->search() on the current_result_set, change resultset class of the result (if needed), and return it in $c->stash->{$self->stash_key}->{$self->data_root}. Please see the individual methods for more details on what actual processing takes place.
352 If the L</select> config param is defined then the hashes will contain only those columns, otherwise all columns in the object will be returned. L</select> of course supports the function/procedure calling semantics that L<DBIx::Class::ResultSet/select>. In order to have proper column names in the result, provide arguments in L</as> (which also follows L<DBIx::Class::ResultSet/as> semantics. Similarly L</count>, L</page>, L</grouped_by> and L</ordered_by> affect the maximum number of rows returned as well as the ordering and grouping. Note that if select, count, ordered_by or grouped_by request parameters are present then these will override the values set on the class with select becoming bound by the select_exposes attribute.
354 If not all objects in the resultset are required then it's possible to pass conditions to the method as request parameters. You can use a JSON string as the 'search' parameter for maximum flexibility or use L<CGI::Expand> syntax. In the second case the request parameters are expanded into a structure and then used as the search condition.
356 For example, these request parameters:
358 ?search.name=fred&search.cd.artist=luke
360 ?search={"name":"fred","cd": {"artist":"luke"}}
362 Would result in this search (where 'name' is a column of the schema class, 'cd' is a relation of the schema class and 'artist' is a column of the related class):
364 $rs->search({ name => 'fred', 'cd.artist' => 'luke' }, { join => ['cd'] })
366 It is also possible to use a JSON string for expandeded parameters:
368 ?search.datetime={"-between":["2010-01-06 19:28:00","2010-01-07 19:28:00"]}
370 Note that if pagination is needed, this can be achieved using a combination of the L</count> and L</page> parameters. For example:
374 Would result in this search:
376 $rs->search({}, { page => 2, rows => 20 })
381 my ( $self, $c ) = @_;
383 $self->list_munge_parameters($c);
384 $self->list_perform_search($c);
385 $self->list_format_output($c);
387 # make sure there are no objects lingering
388 $c->req->clear_objects();
391 =method_protected list_munge_parameters
393 list_munge_parameters is a noop by default. All arguments will be passed through without any manipulation. In order to successfully manipulate the parameters before the search is performed, simply access $c->req->search_parameters|search_attributes (ArrayRef and HashRef respectively), which correspond directly to ->search($parameters, $attributes). Parameter keys will be in already-aliased form.
394 To store the munged parameters call $c->req->_set_search_parameters($newparams) and $c->req->_set_search_attributes($newattrs).
398 sub list_munge_parameters { } # noop by default
400 =method_protected list_perform_search
402 list_perform_search executes the actual search. current_result_set is updated to contain the result returned from ->search. If paging was requested, search_total_entries will be set as well.
406 sub list_perform_search {
407 my ( $self, $c ) = @_;
413 $req->current_result_set->search( $req->search_parameters,
414 $req->search_attributes );
416 $req->_set_current_result_set($rs);
418 $req->_set_search_total_entries(
419 $req->current_result_set->pager->total_entries )
420 if $req->has_search_attributes
421 && ( exists( $req->search_attributes->{page} )
422 && defined( $req->search_attributes->{page} )
423 && length( $req->search_attributes->{page} ) );
427 $self->push_error( $c,
428 { message => 'a database error has occured.' } );
433 =method_protected list_format_output
435 list_format_output prepares the response for transmission across the wire. A copy of the current_result_set is taken and its result_class is set to L<DBIx::Class::ResultClass::HashRefInflator>. Each row in the resultset is then iterated and passed to L</row_format_output> with the result of that call added to the output.
439 sub list_format_output {
440 my ( $self, $c ) = @_;
442 my $rs = $c->req->current_result_set->search;
443 $rs->result_class( $self->result_class ) if $self->result_class;
449 foreach my $row ( $rs->all ) {
450 push( @$formatted, $self->row_format_output( $c, $row ) );
453 $output->{ $self->data_root } = $formatted;
455 if ( $c->req->has_search_total_entries ) {
456 $output->{ $self->total_entries_arg } =
457 $c->req->search_total_entries + 0;
460 $c->stash->{ $self->stash_key } = $output;
464 $self->push_error( $c,
465 { message => 'a database error has occured.' } );
470 =method_protected row_format_output
472 row_format_output is called each row of the inflated output generated from the search. It receives two arguments, the catalyst context and the hashref that represents the row. By default, this method is merely a passthrough.
476 sub row_format_output {
478 #my ($self, $c, $row) = @_;
479 my ( $self, undef, $row ) = @_;
480 return $row; # passthrough by default
483 =method_protected item
485 item will return a single object called by identifier in the uri. It will be inflated via each_object_inflate.
490 my ( $self, $c ) = @_;
492 if ( $c->req->count_objects != 1 ) {
494 $self->push_error( $c,
495 { message => 'No objects on which to operate' } );
499 $c->stash->{ $self->stash_key }->{ $self->item_root } =
500 $self->each_object_inflate( $c, $c->req->get_object(0)->[0] );
504 =method_protected update_or_create
506 update_or_create is responsible for iterating any stored objects and performing updates or creates. Each object is first validated to ensure it meets the criteria specified in the L</create_requires> and L</create_allows> (or L</update_allows>) parameters of the controller config. The objects are then committed within a transaction via L</transact_objects> using a closure around L</save_objects>.
510 sub update_or_create {
511 my ( $self, $c ) = @_;
513 if ( $c->req->has_objects ) {
514 $self->validate_objects($c);
515 $self->transact_objects( $c, sub { $self->save_objects( $c, @_ ) } );
519 $self->push_error( $c,
520 { message => 'No objects on which to operate' } );
525 =method_protected transact_objects
527 transact_objects performs the actual commit to the database via $schema->txn_do. This method accepts two arguments, the context and a coderef to be used within the transaction. All of the stored objects are passed as an arrayref for the only argument to the coderef.
531 sub transact_objects {
532 my ( $self, $c, $coderef ) = @_;
535 $self->stored_result_source->schema->txn_do( $coderef,
540 $self->push_error( $c,
541 { message => 'a database error has occured.' } );
546 =method_protected validate_objects
548 This is a shortcut method for performing validation on all of the stored objects in the request. Each object's provided values (for create or update) are updated to the allowed values permitted by the various config parameters.
552 sub validate_objects {
553 my ( $self, $c ) = @_;
556 foreach my $obj ( $c->req->all_objects ) {
557 $obj->[1] = $self->validate_object( $c, $obj );
562 $c->log->error($err);
563 $err =~ s/\s+at\s+.+\n$//g;
564 $self->push_error( $c, { message => $err } );
569 =method_protected validate_object
571 validate_object takes the context and the object as an argument. It then filters the passed values in slot two of the tuple through the create|update_allows configured. It then returns those filtered values. Values that are not allowed are silently ignored. If there are no values for a particular key, no valid values at all, or multiple of the same key, this method will die.
575 sub validate_object {
576 my ( $self, $c, $obj ) = @_;
577 my ( $object, $params ) = @$obj;
580 my %requires_map = map { $_ => 1 } @{
581 ( $object->in_storage )
583 : $c->stash->{create_requires} || $self->create_requires
586 my %allows_map = map { ( ref $_ ) ? %{$_} : ( $_ => 1 ) } (
588 @{ ( $object->in_storage )
589 ? ( $c->stash->{update_allows} || $self->update_allows )
590 : ( $c->stash->{create_allows} || $self->create_allows )
594 foreach my $key ( keys %allows_map ) {
596 # check value defined if key required
597 my $allowed_fields = $allows_map{$key};
599 if ( ref $allowed_fields ) {
600 my $related_source = $object->result_source->related_source($key);
601 my $related_params = $params->{$key};
602 my %allowed_related_map = map { $_ => 1 } @$allowed_fields;
603 my $allowed_related_cols =
604 ( $allowed_related_map{'*'} )
605 ? [ $related_source->columns ]
608 foreach my $related_col ( @{$allowed_related_cols} ) {
610 my $related_col_value =
611 $related_params->{$related_col}
615 $values{$key}{$related_col} = $related_col_value;
620 my $value = $params->{$key};
622 if ( $requires_map{$key} ) {
623 unless ( defined($value) ) {
625 # if not defined look for default
626 $value = $object->result_source->column_info($key)
628 unless ( defined $value ) {
629 die "No value supplied for ${key} and no default";
634 # check for multiple values
635 if ( ref($value) && !( reftype($value) eq reftype(JSON::true) ) )
637 require Data::Dumper;
639 "Multiple values for '${key}': ${\Data::Dumper::Dumper($value)}";
642 # check exists so we don't just end up with hash of undefs
643 # check defined to account for default values being used
644 $values{$key} = $value
645 if exists $params->{$key} || defined $value;
649 unless ( keys %values || !$object->in_storage ) {
650 die 'No valid keys passed';
656 =method_protected delete
658 delete operates on the stored objects in the request. It first transacts the objects, deleting them in the database using L</transact_objects> and a closure around L</delete_objects>, and then clears the request store of objects.
663 my ( $self, $c ) = @_;
665 if ( $c->req->has_objects ) {
666 $self->transact_objects( $c,
667 sub { $self->delete_objects( $c, @_ ) } );
668 $c->req->clear_objects;
672 $self->push_error( $c,
673 { message => 'No objects on which to operate' } );
678 =method_protected save_objects
680 This method is used by update_or_create to perform the actual database manipulations. It iterates each object calling L</save_object>.
685 my ( $self, $c, $objects ) = @_;
687 foreach my $obj (@$objects) {
688 $self->save_object( $c, $obj );
692 =method_protected save_object
694 save_object first checks to see if the object is already in storage. If so, it calls L</update_object_from_params> otherwise it calls L</insert_object_from_params>
699 my ( $self, $c, $obj ) = @_;
701 my ( $object, $params ) = @$obj;
703 if ( $object->in_storage ) {
704 $self->update_object_from_params( $c, $object, $params );
707 $self->insert_object_from_params( $c, $object, $params );
712 =method_protected update_object_from_params
714 update_object_from_params iterates through the params to see if any of them are pertinent to relations. If so it calls L</update_object_relation> with the object, and the relation parameters. Then it calls ->update on the object.
718 sub update_object_from_params {
719 my ( $self, $c, $object, $params ) = @_;
721 foreach my $key ( keys %$params ) {
722 my $value = $params->{$key};
723 if ( ref($value) && !( reftype($value) eq reftype(JSON::true) ) ) {
724 $self->update_object_relation( $c, $object,
725 delete $params->{$key}, $key );
729 elsif ( $object->can($key) ) {
730 $object->$key($value);
733 # accessor != colname
736 $object->result_source->column_info($key)->{accessor};
737 $object->$accessor($value);
744 =method_protected update_object_relation
746 update_object_relation finds the relation to the object, then calls ->update with the specified parameters
750 sub update_object_relation {
751 my ( $self, $c, $object, $related_params, $relation ) = @_;
752 my $row = $object->find_related( $relation, {}, {} );
755 foreach my $key ( keys %$related_params ) {
756 my $value = $related_params->{$key};
757 if ( ref($value) && !( reftype($value) eq reftype(JSON::true) ) )
759 $self->update_object_relation( $c, $row,
760 delete $related_params->{$key}, $key );
764 elsif ( $row->can($key) ) {
768 # accessor != colname
771 $row->result_source->column_info($key)->{accessor};
772 $row->$accessor($value);
778 $object->create_related( $relation, $related_params );
782 =method_protected insert_object_from_params
784 insert_object_from_params sets the columns for the object, then calls ->insert
788 sub insert_object_from_params {
790 #my ($self, $c, $object, $params) = @_;
791 my ( $self, undef, $object, $params ) = @_;
794 while ( my ( $key, $value ) = each %{$params} ) {
795 if ( ref($value) && !( reftype($value) eq reftype(JSON::true) ) ) {
796 $rels{$key} = $value;
800 elsif ( $object->can($key) ) {
801 $object->$key($value);
804 # accessor != colname
807 $object->result_source->column_info($key)->{accessor};
808 $object->$accessor($value);
814 while ( my ( $k, $v ) = each %rels ) {
815 $object->create_related( $k, $v );
819 =method_protected delete_objects
821 delete_objects iterates through each object calling L</delete_object>
826 my ( $self, $c, $objects ) = @_;
828 map { $self->delete_object( $c, $_->[0] ) } @$objects;
831 =method_protected delete_object
833 Performs the actual ->delete on the object
839 #my ($self, $c, $object) = @_;
840 my ( $self, undef, $object ) = @_;
845 =method_protected end
847 end performs the final manipulation of the response before it is serialized. This includes setting the success of the request both at the HTTP layer and JSON layer. If configured with return_object true, and there are stored objects as the result of create or update, those will be inflated according to the schema and get_inflated_columns
852 my ( $self, $c ) = @_;
854 # don't change the http status code if already set elsewhere
855 unless ( $c->res->status && $c->res->status != 200 ) {
856 if ( $self->has_errors($c) ) {
857 $c->res->status(400);
860 $c->res->status(200);
864 if ( $c->res->status == 200 ) {
865 $c->stash->{ $self->stash_key }->{success} =
866 $self->use_json_boolean ? JSON::true : 'true';
867 if ( $self->return_object && $c->req->has_objects ) {
868 my $returned_objects = [];
869 push( @$returned_objects, $self->each_object_inflate( $c, $_ ) )
870 for map { $_->[0] } $c->req->all_objects;
871 $c->stash->{ $self->stash_key }->{ $self->data_root } =
872 scalar(@$returned_objects) > 1
874 : $returned_objects->[0];
878 $c->stash->{ $self->stash_key }->{success} =
879 $self->use_json_boolean ? JSON::false : 'false';
880 $c->stash->{ $self->stash_key }->{messages} = $self->get_errors($c)
881 if $self->has_errors($c);
883 # don't return data for error responses
884 delete $c->stash->{ $self->stash_key }->{ $self->data_root };
887 $c->forward('serialize');
890 =method_protected each_object_inflate
892 each_object_inflate executes during L</end> and allows hooking into the process of inflating the objects to return in the response. Receives, the context, and the object as arguments.
894 This only executes if L</return_object> if set and if there are any objects to actually return.
898 sub each_object_inflate {
900 #my ($self, $c, $object) = @_;
901 my ( $self, undef, $object ) = @_;
903 return { $object->get_columns };
906 =method_protected serialize
908 multiple actions forward to serialize which uses Catalyst::Action::Serialize.
912 # from Catalyst::Action::Serialize
913 sub serialize : ActionClass('Serialize') { }
915 =method_protected push_error
917 push_error stores an error message into the stash to be later retrieved by L</end>. Accepts a Dict[message => Str] parameter that defines the error message.
922 my ( $self, $c, $params ) = @_;
923 die 'Catalyst app object missing'
925 my $error = 'unknown error';
926 if ( exists $params->{message} ) {
927 $error = $params->{message};
929 # remove newline from die "error message\n" which is required to not
930 # have the filename and line number in the error text
933 push( @{ $c->stash->{_dbic_crud_errors} }, $error );
936 =method_protected get_errors
938 get_errors returns all of the errors stored in the stash
943 my ( $self, $c ) = @_;
944 die 'Catalyst app object missing'
946 return $c->stash->{_dbic_crud_errors};
949 =method_protected has_errors
951 returns returns true if errors are stored in the stash
956 my ( $self, $c ) = @_;
957 die 'Catalyst app object missing'
959 return exists $c->stash->{_dbic_crud_errors};
964 Easily provide common API endpoints based on your L<DBIx::Class> schema classes. Module provides both RPC and REST interfaces to base functionality. Uses L<Catalyst::Action::Serialize> and L<Catalyst::Action::Deserialize> to serialise response and/or deserialise request.
968 This document describes base functionlity such as list, create, delete, update and the setting of config attributes. L<Catalyst::Controller::DBIC::API::RPC> and L<Catalyst::Controller::DBIC::API::REST> describe details of provided endpoints to those base methods.
970 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::DBIC::API::REST>. Similarly if you wanted to provide an RPC style interface then subclass L<Catalyst::Controller::DBIC::API::RPC>. You then configure these individually as specified in L</CONFIGURATION>.
972 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.
976 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>.
978 The class, create_requires, create_allows and update_requires parameters can also be set in the stash like so:
980 sub setup :Chained('/api/rpc/rpc_base') :CaptureArgs(1) :PathPart('any') {
981 my ($self, $c, $object_type) = @_;
983 if ($object_type eq 'artist') {
984 $c->stash->{class} = 'MyAppDB::Artist';
985 $c->stash->{create_requires} = [qw/name/];
986 $c->stash->{update_allows} = [qw/name/];
988 $self->push_error($c, { message => "invalid object_type" });
992 $self->next::method($c);
995 Generally it's better to have one controller for each DBIC source with the config hardcoded, but in some cases this isn't possible.
997 Note that the Chained, CaptureArgs and PathPart are just standard Catalyst configuration parameters and that then endpoint specified in Chained - in this case '/api/rpc/rpc_base' - must actually exist elsewhere in your application. See L<Catalyst::DispatchType::Chained> for more details.
999 Below are explanations for various configuration parameters. Please see L<Catalyst::Controller::DBIC::API::StaticArguments> for more details.
1003 Whatever you would pass to $c->model to get a resultset for this class. MyAppDB::Track for example.
1005 =head3 resultset_class
1007 Desired resultset class after accessing your model. MyAppDB::ResultSet::Track for example. By default, it's DBIx::Class::ResultClass::HashRefInflator. Set to empty string to leave resultset class without change.
1011 Controls where in stash request_data should be stored, and defaults to 'response'.
1015 By default, the response data is serialized into $c->stash->{$self->stash_key}->{$self->data_root} and data_root defaults to 'list' to preserve backwards compatibility. This is now configuable to meet the needs of the consuming client.
1017 =head3 use_json_boolean
1019 By default, the response success status is set to a string value of "true" or "false". If this attribute is true, JSON's true() and false() will be used instead. Note, this does not effect other internal processing of boolean values.
1021 =head3 count_arg, page_arg, select_arg, search_arg, grouped_by_arg, ordered_by_arg, prefetch_arg, as_arg, total_entries_arg
1023 These attributes allow customization of the component to understand requests made by clients where these argument names are not flexible and cannot conform to this components defaults.
1025 =head3 create_requires
1027 Arrayref listing columns required to be passed to create in order for the request to be valid.
1029 =head3 create_allows
1031 Arrayref listing columns additional to those specified in create_requires that are not required to create but which create does allow. Columns passed to create that are not listed in create_allows or create_requires will be ignored.
1033 =head3 update_allows
1035 Arrayref listing columns that update will allow. Columns passed to update that are not listed here will be ignored.
1039 Arguments to pass to L<DBIx::Class::ResultSet/select> when performing search for L</list>.
1043 Complements arguments passed to L<DBIx::Class::ResultSet/select> when performing a search. This allows you to specify column names in the result for RDBMS functions, etc.
1045 =head3 select_exposes
1047 Columns and related columns that are okay to return in the resultset since clients can request more or less information specified than the above select argument.
1051 Arguments to pass to L<DBIx::Class::ResultSet/prefetch> when performing search for L</list>.
1053 =head3 prefetch_allows
1055 Arrayref listing relationships that are allowed to be prefetched.
1056 This is necessary to avoid denial of service attacks in form of
1057 queries which would return a large number of data
1058 and unwanted disclosure of data.
1062 Arguments to pass to L<DBIx::Class::ResultSet/group_by> when performing search for L</list>.
1066 Arguments to pass to L<DBIx::Class::ResultSet/order_by> when performing search for L</list>.
1068 =head3 search_exposes
1070 Columns and related columns that are okay to search on. For example if only the position column and all cd columns were to be allowed
1072 search_exposes => [qw/position/, { cd => ['*'] }]
1074 You can also use this to allow custom columns should you wish to allow them through in order to be caught by a custom resultset. For example:
1076 package RestTest::Controller::API::RPC::TrackExposed;
1082 search_exposes => [qw/position title custom_column/],
1085 and then in your custom resultset:
1087 package RestTest::Schema::ResultSet::Track;
1089 use base 'RestTest::Schema::ResultSet';
1093 my ($clause, $params) = @_;
1096 if (my $pretend = delete $clause->{custom_column}) {
1097 $clause->{'cd.year'} = $pretend;
1099 my $rs = $self->SUPER::search(@_);
1104 Arguments to pass to L<DBIx::Class::ResultSet/rows> when performing search for L</list>.
1108 Arguments to pass to L<DBIx::Class::ResultSet/page> when performing search for L</list>.
1112 By default the create, delete and update actions will not return anything apart from the success parameter set in L</end>, often this is not ideal but the required behaviour varies from application to application. So normally it's sensible to write an intermediate class which your main controller classes subclass from.
1114 For example if you wanted create to return the JSON for the newly created object you might have something like:
1116 package MyApp::ControllerBase::DBIC::API::RPC;
1119 BEGIN { extends 'Catalyst::Controller::DBIC::API::RPC' };
1121 sub create :Chained('setup') :Args(0) :PathPart('create') {
1122 my ($self, $c) = @_;
1124 # $c->req->all_objects will contain all of the created
1125 $self->next::method($c);
1127 if ($c->req->has_objects) {
1128 # $c->stash->{$self->stash_key} will be serialized in the end action
1129 $c->stash->{$self->stash_key}->{$self->data_root} = [ map { { $_->get_inflated_columns } } ($c->req->all_objects) ] ;
1133 package MyApp::Controller::API::RPC::Track;
1136 BEGIN { extends 'MyApp::ControllerBase::DBIC::API::RPC' };
1139 It should be noted that the return_object attribute will produce the above result for you, free of charge.
1141 Similarly you might want create, update and delete to all forward to the list action once they are done so you can refresh your view. This should also be simple enough.
1143 If more extensive customization is required, it is recommened to peer into the roles that comprise the system and make use
1147 It should be noted that version 1.004 and above makes a rapid depature from the status quo. The internals were revamped to use more modern tools such as Moose and its role system to refactor functionality out into self-contained roles.
1149 To this end, internally, this module now understands JSON boolean values (as represented by the JSON module) and will Do The Right Thing in handling those values. This means you can have ColumnInflators installed that can covert between JSON booleans and whatever your database wants for boolean values.
1151 Validation for various *_allows or *_exposes is now accomplished via Data::DPath::Validator with a lightly simplified, via subclass, Data::DPath::Validator::Visitor. The rough jist of the process goes as follows: Arguments provided to those attributes are fed into the Validator and Data::DPaths are generated. Then, incoming requests are validated against these paths generated. The validator is set in "loose" mode meaning only one path is required to match. For more information, please see L<Data::DPath::Validator> and more specifically L<Catalyst::Controller::DBIC::API::Validator>.
1154 Transactions are used. The stash is put aside in favor of roles applied to the request object with additional accessors.
1155 Error handling is now much more consistent with most errors immediately detaching.
1156 The internals are much easier to read and understand with lots more documentation.