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;
18 with 'Catalyst::Controller::DBIC::API::StoredResultSource';
19 with 'Catalyst::Controller::DBIC::API::StaticArguments';
20 with 'Catalyst::Controller::DBIC::API::RequestArguments' => { static => 1 };
22 __PACKAGE__->config();
26 package MyApp::Controller::API::RPC::Artist;
28 BEGIN { extends 'Catalyst::Controller::DBIC::API::RPC' }
31 ( action => { setup => { PathPart => 'artist', Chained => '/api/rpc/rpc_base' } }, # define parent chain action and partpath
32 class => 'MyAppDB::Artist', # DBIC schema class
33 create_requires => ['name', 'age'], # columns required to create
34 create_allows => ['nickname'], # additional non-required columns that create allows
35 update_allows => ['name', 'age', 'nickname'], # columns that update allows
36 update_allows => ['name', 'age', 'nickname'], # columns that update allows
37 select => [qw/name age/], # columns that data returns
38 prefetch => ['cds'], # relationships that are prefetched when no prefetch param is passed
39 prefetch_allows => [ # every possible prefetch param allowed
43 { cds => [qw/ tracks /] }
45 ordered_by => [qw/age/], # order of generated list
46 search_exposes => [qw/age nickname/, { cds => [qw/title year/] }], # columns that can be searched on via list
47 data_root => 'data' # defaults to "list" for backwards compatibility
48 use_json_boolean => 1, # use JSON::Any::true|false in the response instead of strings
49 return_object => 1, # makes create and update actions return the object
52 # Provides the following functional endpoints:
53 # /api/rpc/artist/create
54 # /api/rpc/artist/list
55 # /api/rpc/artist/id/[id]/delete
56 # /api/rpc/artist/id/[id]/update
59 =method_protected begin
63 A begin method is provided to apply the L<Catalyst::Controller::DBIC::API::Request> role to $c->request, and perform deserialization and validation of request parameters
72 Catalyst::Controller::DBIC::API::Request->meta->apply($c->req)
73 unless Moose::Util::does_role($c->req, 'Catalyst::Controller::DBIC::API::Request');
74 $c->forward('deserialize');
77 =method_protected setup
79 :Chained('specify.in.subclass.config') :CaptureArgs(0) :PathPart('specify.in.subclass.config')
81 This action is the chain root of the controller. It must either be overridden or configured to provide a base pathpart to the action and also a parent action. For example, for class MyAppDB::Track you might have
83 package MyApp::Controller::API::RPC::Track;
84 use base qw/Catalyst::Controller::DBIC::API::RPC/;
87 ( action => { setup => { PathPart => 'track', Chained => '/api/rpc/rpc_base' } },
93 sub setup :Chained('/api/rpc_base') :CaptureArgs(0) :PathPart('track') {
96 $self->next::method($c);
99 This action will populate $c->req->current_result_set with $self->stored_result_source->resultset for other actions in the chain to use.
103 sub setup :Chained('specify.in.subclass.config') :CaptureArgs(0) :PathPart('specify.in.subclass.config')
108 $c->req->_set_current_result_set($self->stored_result_source->resultset);
111 =method_protected object
113 :Chained('setup') :CaptureArgs(1) :PathPart('')
115 This action is the chain root for all object level actions (such as delete and update). If an identifier is passed it will be used to find that particular object and add it to the request's store of objects. Otherwise, the data stored at the data_root of the request_data will be interpreted as an array of objects 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. Please see L<Catalyst::Controller::DBIC::API::Context> for more details on the stored objects.
119 sub object :Chained('setup') :CaptureArgs(1) :PathPart('')
121 my ($self, $c, $id) = @_;
123 my $vals = $c->req->request_data->{$self->data_root};
124 unless(defined($vals))
126 # no data root, assume the request_data itself is the payload
127 $vals = [$c->req->request_data || {}];
129 elsif(reftype($vals) eq 'HASH')
138 # there can be only one set of data
139 $c->req->add_object([$self->object_lookup($c, $id), $vals->[0]]);
144 $self->push_error($c, { message => $_ });
150 unless(reftype($vals) eq 'ARRAY')
152 $c->log->error('Invalid request data');
153 $self->push_error($c, { message => 'Invalid request data' });
157 foreach my $val (@$vals)
159 unless(exists($val->{id}))
161 $c->req->add_object([$c->req->current_result_set->new_result({}), $val]);
167 $c->req->add_object([$self->object_lookup($c, $val->{id}), $val]);
172 $self->push_error($c, { message => $_ });
179 =method_protected object_lookup
181 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.
187 my ($self, $c, $id) = @_;
189 die 'No valid ID provided for look up' unless defined $id and length $id;
190 my $object = $c->req->current_result_set->find($id);
191 die "No object found for id '$id'" unless defined $object;
195 =method_protected deserialize
197 deserialize absorbs the request data and transforms it into useful bits by using CGI::Expand->expand_hash and a smattering of JSON::Any->from_json for a handful of arguments. Current only the following arguments are capable of being expressed as JSON:
206 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.
210 sub deserialize :ActionClass('Deserialize')
216 if ($c->req->data && scalar(keys %{$c->req->data}))
218 $req_params = $c->req->data;
222 $req_params = CGI::Expand->expand_hash($c->req->params);
224 foreach my $param (@{[$self->search_arg, $self->count_arg, $self->page_arg, $self->offset_arg, $self->ordered_by_arg, $self->grouped_by_arg, $self->prefetch_arg]})
226 # these params can also be composed of JSON
227 # but skip if the parameter is not provided
228 next if not exists $req_params->{$param};
229 # find out if CGI::Expand was involved
230 if (ref $req_params->{$param} eq 'HASH')
232 for my $key ( keys %{$req_params->{$param}} )
236 my $deserialized = JSON::Any->from_json($req_params->{$param}->{$key});
237 $req_params->{$param}->{$key} = $deserialized;
241 $c->log->debug("Param '$param.$key' did not deserialize appropriately: $_")
250 my $deserialized = JSON::Any->from_json($req_params->{$param});
251 $req_params->{$param} = $deserialized;
255 $c->log->debug("Param '$param' did not deserialize appropriately: $_")
262 $self->inflate_request($c, $req_params);
265 =method_protected inflate_request
267 inflate_request is called at the end of deserialize to populate key portions of the request with the useful bits
274 my ($self, $c, $params) = @_;
278 # set static arguments
279 $c->req->_set_controller($self);
281 # set request arguments
282 $c->req->_set_request_data($params);
288 $self->push_error($c, { message => $_ });
294 =method_protected list
298 List level action chained from L</setup>. List's steps are broken up into three distinct methods: L</list_munge_parameters>, L</list_perform_search>, and L</list_format_output>.
300 The goal of this method is to call ->search() on the current_result_set, HashRefInflator the result, and return it in $c->stash->{response}->{$self->data_root}. Pleasee see the individual methods for more details on what actual processing takes place.
302 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.
304 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.
306 For example, these request parameters:
308 ?search.name=fred&search.cd.artist=luke
310 ?search={"name":"fred","cd": {"artist":"luke"}}
312 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):
314 $rs->search({ name => 'fred', 'cd.artist' => 'luke' }, { join => ['cd'] })
316 It is also possible to use a JSON string for expandeded parameters:
318 ?search.datetime={"-between":["2010-01-06 19:28:00","2010-01-07 19:28:00"]}
320 Note that if pagination is needed, this can be achieved using a combination of the L</count> and L</page> parameters. For example:
324 Would result in this search:
326 $rs->search({}, { page => 2, rows => 20 })
335 $self->list_munge_parameters($c);
336 $self->list_perform_search($c);
337 $self->list_format_output($c);
340 =method_protected list_munge_parameters
342 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.
346 sub list_munge_parameters { } # noop by default
348 =method_protected list_perform_search
350 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.
354 sub list_perform_search
363 my $rs = $req->current_result_set->search
365 $req->search_parameters,
366 $req->search_attributes
369 $req->_set_current_result_set($rs);
371 $req->_set_search_total_entries($req->current_result_set->pager->total_entries)
372 if $req->has_search_attributes &&
374 (exists($req->search_attributes->{page}) && defined($req->search_attributes->{page}) && length($req->search_attributes->{page}))
375 ||(exists($req->search_attributes->{offset}) && defined($req->search_attributes->{offset}) && length($req->search_attributes->{offset}))
376 ||(exists($req->search_attributes->{rows}) && defined($req->search_attributes->{rows}) && length($req->search_attributes->{rows}))
382 $self->push_error($c, { message => 'a database error has occured.' });
387 =method_protected list_format_output
389 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.
393 sub list_format_output
398 my $rs = $c->req->current_result_set->search;
399 $rs->result_class('DBIx::Class::ResultClass::HashRefInflator');
406 foreach my $row ($rs->all)
408 push(@$formatted, $self->row_format_output($row));
411 $output->{$self->data_root} = $formatted;
413 if ($c->req->has_search_total_entries)
415 $output->{$self->total_entries_arg} = $c->req->search_total_entries + 0;
418 $c->stash->{response} = $output;
423 $self->push_error($c, { message => 'a database error has occured.' });
428 =method_protected row_format_output
430 row_format_output is called each row of the inflated output generated from the search. It receives only one argument, the hashref that represents the row. By default, this method is merely a passthrough.
434 sub row_format_output { shift; shift; } # passthrough by default
436 =method_protected update_or_create
440 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>.
444 sub update_or_create :Private
449 if($c->req->has_objects)
451 $self->validate_objects($c);
452 $self->transact_objects($c, \&save_objects);
457 $self->push_error($c, { message => 'No objects on which to operate' });
462 =method_protected transact_objects
464 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.
471 my ($self, $c, $coderef) = @_;
475 $self->stored_result_source->schema->txn_do
484 $self->push_error($c, { message => 'a database error has occured.' });
489 =method_protected validate_objects
491 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.
502 foreach my $obj ($c->req->all_objects)
504 $obj->[1] = $self->validate_object($c, $obj);
510 $c->log->error($err);
511 $err =~ s/\s+at\s+\/.+\n$//g;
512 $self->push_error($c, { message => $err });
517 =method_protected validate_object
519 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.
526 my ($self, $c, $obj) = @_;
527 my ($object, $params) = @$obj;
530 my %requires_map = map
535 ($object->in_storage)
537 : $c->stash->{create_requires} || $self->create_requires
542 (ref $_) ? %{$_} : ($_ => 1)
547 ($object->in_storage)
548 ? ($c->stash->{update_allows} || $self->update_allows)
549 : ($c->stash->{create_allows} || $self->create_allows)
553 foreach my $key (keys %allows_map)
555 # check value defined if key required
556 my $allowed_fields = $allows_map{$key};
558 if (ref $allowed_fields)
560 my $related_source = $object->result_source->related_source($key);
561 my $related_params = $params->{$key};
562 my %allowed_related_map = map { $_ => 1 } @$allowed_fields;
563 my $allowed_related_cols = ($allowed_related_map{'*'}) ? [$related_source->columns] : $allowed_fields;
565 foreach my $related_col (@{$allowed_related_cols})
567 if (my $related_col_value = $related_params->{$related_col}) {
568 $values{$key}{$related_col} = $related_col_value;
574 my $value = $params->{$key};
576 if ($requires_map{$key})
578 unless (defined($value))
580 # if not defined look for default
581 $value = $object->result_source->column_info($key)->{default_value};
582 unless (defined $value)
584 die "No value supplied for ${key} and no default";
589 # check for multiple values
590 if (ref($value) && !($value == JSON::Any::true || $value == JSON::Any::false))
592 require Data::Dumper;
593 die "Multiple values for '${key}': ${\Data::Dumper::Dumper($value)}";
596 # check exists so we don't just end up with hash of undefs
597 # check defined to account for default values being used
598 $values{$key} = $value if exists $params->{$key} || defined $value;
602 unless (keys %values || !$object->in_storage)
604 die 'No valid keys passed';
610 =method_protected delete
614 delete operates on the stored objects in the request. It first transacts the objects, deleting them in the database, and then clears the request store of objects.
623 if($c->req->has_objects)
625 $self->transact_objects($c, \&delete_objects);
626 $c->req->clear_objects;
631 $self->push_error($c, { message => 'No objects on which to operate' });
636 =head1 HELPER FUNCTIONS
638 This functions are only helper functions and should have a void invocant. If they are called as methods, they will die. The only reason they are stored in the class is to allow for customization without rewriting the methods that make use of these helper functions.
642 This helper function is used by update_or_create to perform the actual database manipulations.
644 =head2 delete_objects
646 This helper function is used by delete to perform the actual database delete of objects.
654 die 'save_objects coderef had an invocant and shouldn\'t have had one' if blessed($objects);
656 foreach my $obj (@$objects)
658 my ($object, $params) = @$obj;
660 if ($object->in_storage) {
661 foreach my $key (keys %{$params}) {
662 my $value = $params->{$key};
663 if (ref($value) && !($value == JSON::Any::true || $value == JSON::Any::false)) {
664 my $related_params = delete $params->{$key};
665 my $row = $object->find_related($key, {} , {});
666 $row->update($related_params);
669 $object->update($params);
671 $object->set_columns($params);
681 die 'delete_objects coderef had an invocant and shouldn\'t have had one' if blessed($objects);
683 map { $_->[0]->delete } @$objects;
686 =method_protected end
690 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
702 # Check for errors caught elsewhere
703 if ( $c->res->status and $c->res->status != 200 ) {
704 $default_status = $c->res->status;
705 $c->stash->{response}->{success} = $self->use_json_boolean ? JSON::Any::false : 'false';
706 } elsif ($self->get_errors($c)) {
707 $c->stash->{response}->{messages} = $self->get_errors($c);
708 $c->stash->{response}->{success} = $self->use_json_boolean ? JSON::Any::false : 'false';
709 $default_status = 400;
711 $c->stash->{response}->{success} = $self->use_json_boolean ? JSON::Any::true : 'true';
712 $default_status = 200;
715 unless ($default_status == 200)
717 delete $c->stash->{response}->{$self->data_root};
719 elsif($self->return_object && $c->req->has_objects)
722 my $returned_objects = [];
723 push(@$returned_objects, $self->each_object_inflate($c, $_)) for map { $_->[0] } $c->req->all_objects;
724 $c->stash->{response}->{$self->data_root} = scalar(@$returned_objects) > 1 ? $returned_objects : $returned_objects->[0];
727 $c->res->status( $default_status || 200 );
728 $c->forward('serialize');
731 =method_protected each_object_inflate
733 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.
735 This only executes if L</return_object> if set and if there are any objects to actually return.
739 sub each_object_inflate
741 my ($self, $c, $object) = @_;
743 return { $object->get_inflated_columns };
746 # from Catalyst::Action::Serialize
747 sub serialize :ActionClass('Serialize') { }
749 =method_protected push_error
751 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.
757 my ( $self, $c, $params ) = @_;
758 push( @{$c->stash->{_dbic_crud_errors}}, $params->{message} || 'unknown error' );
761 =method_protected get_errors
763 get_errors returns all of the errors stored in the stash
769 my ( $self, $c ) = @_;
770 return $c->stash->{_dbic_crud_errors};
775 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.
779 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.
781 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>.
783 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.
787 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>.
789 The class, create_requires, create_allows and update_requires parameters can also be set in the stash like so:
791 sub setup :Chained('/api/rpc/rpc_base') :CaptureArgs(1) :PathPart('any') {
792 my ($self, $c, $object_type) = @_;
794 if ($object_type eq 'artist') {
795 $c->stash->{class} = 'MyAppDB::Artist';
796 $c->stash->{create_requires} = [qw/name/];
797 $c->stash->{update_allows} = [qw/name/];
799 $self->push_error($c, { message => "invalid object_type" });
803 $self->next::method($c);
806 Generally it's better to have one controller for each DBIC source with the config hardcoded, but in some cases this isn't possible.
808 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.
810 Below are explanations for various configuration parameters. Please see L<Catalyst::Controller::DBIC::API::StaticArguments> for more details.
814 Whatever you would pass to $c->model to get a resultset for this class. MyAppDB::Track for example.
818 By default, the response data is serialized into $c->stash->{response}->{$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.
820 =head3 use_json_boolean
822 By default, the response success status is set to a string value of "true" or "false". If this attribute is true, JSON::Any's true() and false() will be used instead. Note, this does not effect other internal processing of boolean values.
824 =head3 count_arg, page_arg, select_arg, search_arg, grouped_by_arg, ordered_by_arg, prefetch_arg, as_arg, total_entries_arg
826 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.
828 =head3 create_requires
830 Arrayref listing columns required to be passed to create in order for the request to be valid.
834 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.
838 Arrayref listing columns that update will allow. Columns passed to update that are not listed here will be ignored.
842 Arguments to pass to L<DBIx::Class::ResultSet/select> when performing search for L</list>.
846 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.
848 =head3 select_exposes
850 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.
854 Arguments to pass to L<DBIx::Class::ResultSet/prefetch> when performing search for L</list>.
856 =head3 prefetch_allows
858 Arrayref listing relationships that are allowed to be prefetched.
859 This is necessary to avoid denial of service attacks in form of
860 queries which would return a large number of data
861 and unwanted disclosure of data.
865 Arguments to pass to L<DBIx::Class::ResultSet/group_by> when performing search for L</list>.
869 Arguments to pass to L<DBIx::Class::ResultSet/order_by> when performing search for L</list>.
871 =head3 search_exposes
873 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
875 search_exposes => [qw/position/, { cd => ['*'] }]
877 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:
879 package RestTest::Controller::API::RPC::TrackExposed;
885 search_exposes => [qw/position title custom_column/],
888 and then in your custom resultset:
890 package RestTest::Schema::ResultSet::Track;
892 use base 'RestTest::Schema::ResultSet';
896 my ($clause, $params) = @_;
899 if (my $pretend = delete $clause->{custom_column}) {
900 $clause->{'cd.year'} = $pretend;
902 my $rs = $self->SUPER::search(@_);
907 Arguments to pass to L<DBIx::Class::ResultSet/rows> when performing search for L</list>.
911 Arguments to pass to L<DBIx::Class::ResultSet/rows> when performing search for L</list>.
915 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.
917 For example if you wanted create to return the JSON for the newly created object you might have something like:
919 package MyApp::ControllerBase::DBIC::API::RPC;
922 BEGIN { extends 'Catalyst::Controller::DBIC::API::RPC' };
924 sub create :Chained('setup') :Args(0) :PathPart('create') {
927 # $c->req->all_objects will contain all of the created
928 $self->next::method($c);
930 if ($c->req->has_objects) {
931 # $c->stash->{response} will be serialized in the end action
932 $c->stash->{response}->{$self->data_root} = [ map { { $_->get_inflated_columns } } ($c->req->all_objects) ] ;
937 package MyApp::Controller::API::RPC::Track;
940 BEGIN { extends 'MyApp::ControllerBase::DBIC::API::RPC' };
943 It should be noted that the return_object attribute will produce the above result for you, free of charge.
945 For REST the only difference besides the class names would be that create should be :Private rather than an endpoint.
947 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.
949 If more extensive customization is required, it is recommened to peer into the roles that comprise the system and make use
953 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.
955 To this end, internally, this module now understands JSON boolean values (as represented by JSON::Any) and will Do The Right Thing in handling those values. This means you can have ColumnInflators installed that can covert between JSON::Any booleans and whatever your database wants for boolean values.
957 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>.
960 Transactions are used. The stash is put aside in favor of roles applied to the request object with additional accessors.
961 Error handling is now much more consistent with most errors immediately detaching.
962 The internals are much easier to read and understand with lots more documentation.