Create related rows if they don't exist already.
[catagits/Catalyst-Controller-DBIC-API.git] / lib / Catalyst / Controller / DBIC / API.pm
CommitLineData
d2739840 1package Catalyst::Controller::DBIC::API;
2
3#ABSTRACT: Provides a DBIx::Class web service automagically
4use Moose;
a784948c 5BEGIN { extends 'Catalyst::Controller::ActionRole'; }
d2739840 6
7use CGI::Expand ();
8use DBIx::Class::ResultClass::HashRefInflator;
9use JSON::Any;
10use Test::Deep::NoTest('eq_deeply');
11use MooseX::Types::Moose(':all');
12use Moose::Util;
13use Scalar::Util('blessed', 'reftype');
14use Try::Tiny;
15use Catalyst::Controller::DBIC::API::Request;
16use namespace::autoclean;
17
18with 'Catalyst::Controller::DBIC::API::StoredResultSource';
19with 'Catalyst::Controller::DBIC::API::StaticArguments';
20with 'Catalyst::Controller::DBIC::API::RequestArguments' => { static => 1 };
21
22__PACKAGE__->config();
23
24=head1 SYNOPSIS
25
26 package MyApp::Controller::API::RPC::Artist;
27 use Moose;
28 BEGIN { extends 'Catalyst::Controller::DBIC::API::RPC' }
29
30 __PACKAGE__->config
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
40 'cds',
41 qw/ cds /,
42 { cds => 'tracks' },
43 { cds => [qw/ tracks /] }
44 ],
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
50 );
51
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
57=cut
58
533075c7 59=method_private begin
60
61 :Private
62
63begin is provided in the base class to setup the Catalyst Request object, by applying the DBIC::API::Request role.
64
65=cut
66
67sub begin :Private
68{
69 my ($self, $c) = @_;
70
71 Catalyst::Controller::DBIC::API::Request->meta->apply($c->req)
72 unless Moose::Util::does_role($c->req, 'Catalyst::Controller::DBIC::API::Request');
73}
74
d2739840 75=method_protected setup
76
77 :Chained('specify.in.subclass.config') :CaptureArgs(0) :PathPart('specify.in.subclass.config')
78
79This 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
80
81 package MyApp::Controller::API::RPC::Track;
406086f3 82 use Moose;
533075c7 83 BEGIN { extends 'Catalyst::Controller::DBIC::API::RPC'; }
d2739840 84
85 __PACKAGE__->config
406086f3 86 ( action => { setup => { PathPart => 'track', Chained => '/api/rpc/rpc_base' } },
d2739840 87 ...
88 );
89
90 # or
91
92 sub setup :Chained('/api/rpc_base') :CaptureArgs(0) :PathPart('track') {
93 my ($self, $c) = @_;
94
95 $self->next::method($c);
96 }
97
533075c7 98This action does nothing by default.
d2739840 99
100=cut
101
533075c7 102sub setup :Chained('specify.in.subclass.config') :CaptureArgs(0) :PathPart('specify.in.subclass.config') {}
d2739840 103
104=method_protected deserialize
105
533075c7 106 :Chained('setup') :CaptureArgs(0) :PathPart('') :ActionClass('Deserialize')
107
d2739840 108deserialize 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:
109
110 search_arg
111 count_arg
112 page_arg
113 ordered_by_arg
114 grouped_by_arg
115 prefetch_arg
116
533075c7 117It 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.
d2739840 118
119=cut
120
8cf0b66a 121sub deserialize :Chained('setup') :CaptureArgs(0) :PathPart('') :ActionClass('Deserialize')
d2739840 122{
d2739840 123 my ($self, $c) = @_;
124 my $req_params;
125
126 if ($c->req->data && scalar(keys %{$c->req->data}))
127 {
128 $req_params = $c->req->data;
129 }
406086f3 130 else
d2739840 131 {
132 $req_params = CGI::Expand->expand_hash($c->req->params);
133
33003023 134 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]})
d2739840 135 {
136 # these params can also be composed of JSON
137 # but skip if the parameter is not provided
138 next if not exists $req_params->{$param};
139 # find out if CGI::Expand was involved
140 if (ref $req_params->{$param} eq 'HASH')
141 {
142 for my $key ( keys %{$req_params->{$param}} )
143 {
144 try
145 {
146 my $deserialized = JSON::Any->from_json($req_params->{$param}->{$key});
147 $req_params->{$param}->{$key} = $deserialized;
148 }
149 catch
406086f3 150 {
d2739840 151 $c->log->debug("Param '$param.$key' did not deserialize appropriately: $_")
152 if $c->debug;
153 }
154 }
155 }
156 else
157 {
158 try
159 {
160 my $deserialized = JSON::Any->from_json($req_params->{$param});
161 $req_params->{$param} = $deserialized;
162 }
163 catch
406086f3 164 {
d2739840 165 $c->log->debug("Param '$param' did not deserialize appropriately: $_")
166 if $c->debug;
167 }
168 }
169 }
170 }
406086f3 171
d2739840 172 $self->inflate_request($c, $req_params);
173}
174
9a29ee35 175=method_protected generate_rs
176
177generate_rs is used by inflate_request to generate the resultset stored in the current request. It receives $c as its only argument. And by default it merely returns the resultset from the stored_result_source on the controller. Override this method if you need to manipulate the default implementation of getting the resultset from the controller.
178
179=cut
180
181sub generate_rs
182{
183 my ($self, $c) = @_;
184 return $self->stored_result_source->resultset;
185}
186
d2739840 187=method_protected inflate_request
406086f3 188
d2739840 189inflate_request is called at the end of deserialize to populate key portions of the request with the useful bits
190
191=cut
192
193sub inflate_request
194{
d2739840 195 my ($self, $c, $params) = @_;
196
197 try
198 {
199 # set static arguments
406086f3 200 $c->req->_set_controller($self);
d2739840 201
202 # set request arguments
203 $c->req->_set_request_data($params);
8cf0b66a 204
205 # set the current resultset
9a29ee35 206 $c->req->_set_current_result_set($self->generate_rs($c));
406086f3 207
d2739840 208 }
209 catch
210 {
211 $c->log->error($_);
212 $self->push_error($c, { message => $_ });
213 $c->detach();
214 }
8cf0b66a 215}
216
217=method_protected object_with_id
218
219 :Chained('deserialize') :CaptureArgs(1) :PathPart('')
220
221This 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.
222
223=cut
224
225sub object_with_id :Chained('deserialize') :CaptureArgs(1) :PathPart('')
226{
227 my ($self, $c, $id) = @_;
228
229 my $vals = $c->req->request_data->{$self->data_root};
230 unless(defined($vals))
231 {
232 # no data root, assume the request_data itself is the payload
233 $vals = $c->req->request_data;
234 }
235
236 try
237 {
238 # there can be only one set of data
239 $c->req->add_object([$self->object_lookup($c, $id), $vals]);
240 }
241 catch
242 {
243 $c->log->error($_);
244 $self->push_error($c, { message => $_ });
245 $c->detach();
246 }
247}
248
249=method_protected objects_no_id
250
251 :Chained('deserialize') :CaptureArgs(0) :PathPart('')
252
253This 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.
254
255=cut
256
257sub objects_no_id :Chained('deserialize') :CaptureArgs(0) :PathPart('')
258{
259 my ($self, $c) = @_;
406086f3 260
533075c7 261 if($c->req->has_request_data)
8cf0b66a 262 {
533075c7 263 my $data = $c->req->request_data;
264 my $vals;
406086f3 265
533075c7 266 if(exists($data->{$self->data_root}) && defined($data->{$self->data_root}))
8cf0b66a 267 {
533075c7 268 my $root = $data->{$self->data_root};
269 if(reftype($root) eq 'ARRAY')
270 {
271 $vals = $root;
272 }
273 elsif(reftype($root) eq 'HASH')
274 {
275 $vals = [$root];
276 }
277 else
278 {
279 $c->log->error('Invalid request data');
280 $self->push_error($c, { message => 'Invalid request data' });
281 $c->detach();
282 }
8cf0b66a 283 }
533075c7 284 else
8cf0b66a 285 {
533075c7 286 # no data root, assume the request_data itself is the payload
287 $vals = [$c->req->request_data];
8cf0b66a 288 }
533075c7 289
290 foreach my $val (@$vals)
8cf0b66a 291 {
533075c7 292 unless(exists($val->{id}))
293 {
294 $c->req->add_object([$c->req->current_result_set->new_result({}), $val]);
295 next;
296 }
297
298 try
299 {
300 $c->req->add_object([$self->object_lookup($c, $val->{id}), $val]);
301 }
302 catch
303 {
304 $c->log->error($_);
305 $self->push_error($c, { message => $_ });
306 $c->detach();
307 }
8cf0b66a 308 }
309 }
310}
311
312=method_protected object_lookup
313
314This 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.
315
316=cut
317
318sub object_lookup
319{
320 my ($self, $c, $id) = @_;
321
322 die 'No valid ID provided for look up' unless defined $id and length $id;
323 my $object = $c->req->current_result_set->find($id);
324 die "No object found for id '$id'" unless defined $object;
325 return $object;
d2739840 326}
327
328=method_protected list
329
3d85db11 330list's steps are broken up into three distinct methods: L</list_munge_parameters>, L</list_perform_search>, and L</list_format_output>.
d2739840 331
73517f50 332The 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}. Please see the individual methods for more details on what actual processing takes place.
d2739840 333
334If 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.
335
d666a194 336If 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.
d2739840 337
338For example, these request parameters:
339
340 ?search.name=fred&search.cd.artist=luke
341 OR
342 ?search={"name":"fred","cd": {"artist":"luke"}}
343
344Would 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):
345
346 $rs->search({ name => 'fred', 'cd.artist' => 'luke' }, { join => ['cd'] })
347
348It is also possible to use a JSON string for expandeded parameters:
349
350 ?search.datetime={"-between":["2010-01-06 19:28:00","2010-01-07 19:28:00"]}
351
352Note that if pagination is needed, this can be achieved using a combination of the L</count> and L</page> parameters. For example:
353
354 ?page=2&count=20
355
356Would result in this search:
406086f3 357
d2739840 358 $rs->search({}, { page => 2, rows => 20 })
359
360=cut
361
3d85db11 362sub list
d2739840 363{
d2739840 364 my ($self, $c) = @_;
365
366 $self->list_munge_parameters($c);
367 $self->list_perform_search($c);
368 $self->list_format_output($c);
533075c7 369
370 # make sure there are no objects lingering
406086f3 371 $c->req->clear_objects();
d2739840 372}
373
374=method_protected list_munge_parameters
375
376list_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.
377
378=cut
379
380sub list_munge_parameters { } # noop by default
381
382=method_protected list_perform_search
383
384list_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.
385
386=cut
387
388sub list_perform_search
389{
d2739840 390 my ($self, $c) = @_;
406086f3 391
392 try
d2739840 393 {
394 my $req = $c->req;
406086f3 395
d2739840 396 my $rs = $req->current_result_set->search
397 (
406086f3 398 $req->search_parameters,
d2739840 399 $req->search_attributes
400 );
401
402 $req->_set_current_result_set($rs);
403
404 $req->_set_search_total_entries($req->current_result_set->pager->total_entries)
df8f3121 405 if $req->has_search_attributes && (exists($req->search_attributes->{page}) && defined($req->search_attributes->{page}) && length($req->search_attributes->{page}));
d2739840 406 }
407 catch
408 {
409 $c->log->error($_);
410 $self->push_error($c, { message => 'a database error has occured.' });
411 $c->detach();
412 }
413}
414
415=method_protected list_format_output
416
417list_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.
418
419=cut
420
421sub list_format_output
422{
d2739840 423 my ($self, $c) = @_;
424
425 my $rs = $c->req->current_result_set->search;
426 $rs->result_class('DBIx::Class::ResultClass::HashRefInflator');
406086f3 427
d2739840 428 try
429 {
430 my $output = {};
431 my $formatted = [];
406086f3 432
d2739840 433 foreach my $row ($rs->all)
434 {
4cb15235 435 push(@$formatted, $self->row_format_output($c, $row));
d2739840 436 }
406086f3 437
d2739840 438 $output->{$self->data_root} = $formatted;
439
440 if ($c->req->has_search_total_entries)
441 {
442 $output->{$self->total_entries_arg} = $c->req->search_total_entries + 0;
443 }
444
445 $c->stash->{response} = $output;
446 }
447 catch
448 {
449 $c->log->error($_);
450 $self->push_error($c, { message => 'a database error has occured.' });
451 $c->detach();
452 }
453}
454
455=method_protected row_format_output
456
4cb15235 457row_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.
d2739840 458
459=cut
460
4cb15235 461sub row_format_output
462{
463 my ($self, $c, $row) = @_;
464 return $row; # passthrough by default
465}
d2739840 466
609916e5 467=method_protected item
609916e5 468
469item will return a single object called by identifier in the uri. It will be inflated via each_object_inflate.
470
471=cut
472
3d85db11 473sub item
609916e5 474{
475 my ($self, $c) = @_;
476
477 if($c->req->count_objects != 1)
478 {
479 $c->log->error($_);
480 $self->push_error($c, { message => 'No objects on which to operate' });
481 $c->detach();
482 }
483 else
484 {
533075c7 485 $c->stash->{response}->{$self->item_root} = $self->each_object_inflate($c, $c->req->get_object(0)->[0]);
609916e5 486 }
487}
488
d2739840 489=method_protected update_or_create
490
b421ef50 491update_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>.
d2739840 492
493=cut
494
3d85db11 495sub update_or_create
d2739840 496{
d2739840 497 my ($self, $c) = @_;
406086f3 498
d2739840 499 if($c->req->has_objects)
500 {
501 $self->validate_objects($c);
2e978a8c 502 $self->transact_objects($c, sub { $self->save_objects($c, @_) } );
d2739840 503 }
504 else
505 {
506 $c->log->error($_);
507 $self->push_error($c, { message => 'No objects on which to operate' });
508 $c->detach();
509 }
510}
511
512=method_protected transact_objects
513
514transact_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.
515
516=cut
517
518sub transact_objects
519{
d2739840 520 my ($self, $c, $coderef) = @_;
406086f3 521
d2739840 522 try
523 {
524 $self->stored_result_source->schema->txn_do
525 (
526 $coderef,
527 $c->req->objects
528 );
529 }
530 catch
531 {
532 $c->log->error($_);
533 $self->push_error($c, { message => 'a database error has occured.' });
534 $c->detach();
535 }
536}
537
538=method_protected validate_objects
539
540This 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.
541
542=cut
543
544sub validate_objects
545{
d2739840 546 my ($self, $c) = @_;
547
548 try
549 {
550 foreach my $obj ($c->req->all_objects)
551 {
552 $obj->[1] = $self->validate_object($c, $obj);
553 }
554 }
555 catch
556 {
557 my $err = $_;
558 $c->log->error($err);
bec622aa 559 $err =~ s/\s+at\s+.+\n$//g;
d2739840 560 $self->push_error($c, { message => $err });
561 $c->detach();
562 }
563}
564
565=method_protected validate_object
566
567validate_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.
568
569=cut
570
571sub validate_object
572{
d2739840 573 my ($self, $c, $obj) = @_;
574 my ($object, $params) = @$obj;
575
576 my %values;
577 my %requires_map = map
578 {
579 $_ => 1
406086f3 580 }
d2739840 581 @{
406086f3 582 ($object->in_storage)
583 ? []
d2739840 584 : $c->stash->{create_requires} || $self->create_requires
585 };
406086f3 586
d2739840 587 my %allows_map = map
588 {
589 (ref $_) ? %{$_} : ($_ => 1)
406086f3 590 }
d2739840 591 (
406086f3 592 keys %requires_map,
d2739840 593 @{
406086f3 594 ($object->in_storage)
595 ? ($c->stash->{update_allows} || $self->update_allows)
d2739840 596 : ($c->stash->{create_allows} || $self->create_allows)
597 }
598 );
599
600 foreach my $key (keys %allows_map)
601 {
602 # check value defined if key required
603 my $allowed_fields = $allows_map{$key};
406086f3 604
d2739840 605 if (ref $allowed_fields)
606 {
607 my $related_source = $object->result_source->related_source($key);
608 my $related_params = $params->{$key};
609 my %allowed_related_map = map { $_ => 1 } @$allowed_fields;
610 my $allowed_related_cols = ($allowed_related_map{'*'}) ? [$related_source->columns] : $allowed_fields;
406086f3 611
d2739840 612 foreach my $related_col (@{$allowed_related_cols})
613 {
39955b2a 614 if (defined(my $related_col_value = $related_params->{$related_col})) {
d2739840 615 $values{$key}{$related_col} = $related_col_value;
616 }
617 }
618 }
406086f3 619 else
d2739840 620 {
621 my $value = $params->{$key};
622
623 if ($requires_map{$key})
624 {
625 unless (defined($value))
626 {
627 # if not defined look for default
628 $value = $object->result_source->column_info($key)->{default_value};
629 unless (defined $value)
630 {
631 die "No value supplied for ${key} and no default";
632 }
633 }
634 }
406086f3 635
d2739840 636 # check for multiple values
637 if (ref($value) && !($value == JSON::Any::true || $value == JSON::Any::false))
638 {
639 require Data::Dumper;
640 die "Multiple values for '${key}': ${\Data::Dumper::Dumper($value)}";
641 }
642
643 # check exists so we don't just end up with hash of undefs
644 # check defined to account for default values being used
645 $values{$key} = $value if exists $params->{$key} || defined $value;
646 }
647 }
648
406086f3 649 unless (keys %values || !$object->in_storage)
d2739840 650 {
651 die 'No valid keys passed';
652 }
653
406086f3 654 return \%values;
d2739840 655}
656
657=method_protected delete
658
b421ef50 659delete 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.
d2739840 660
661=cut
662
3d85db11 663sub delete
d2739840 664{
d2739840 665 my ($self, $c) = @_;
406086f3 666
d2739840 667 if($c->req->has_objects)
668 {
2e978a8c 669 $self->transact_objects($c, sub { $self->delete_objects($c, @_) });
d2739840 670 $c->req->clear_objects;
671 }
672 else
673 {
674 $c->log->error($_);
675 $self->push_error($c, { message => 'No objects on which to operate' });
676 $c->detach();
677 }
678}
679
b421ef50 680=method_protected save_objects
d2739840 681
b421ef50 682This method is used by update_or_create to perform the actual database manipulations. It iterates each object calling L</save_object>.
d2739840 683
b421ef50 684=cut
685
686sub save_objects
687{
2e978a8c 688 my ($self, $c, $objects) = @_;
d2739840 689
b421ef50 690 foreach my $obj (@$objects)
691 {
2e978a8c 692 $self->save_object($c, $obj);
b421ef50 693 }
694}
d2739840 695
b421ef50 696=method_protected save_object
d2739840 697
b421ef50 698save_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>
d2739840 699
700=cut
701
b421ef50 702sub save_object
d2739840 703{
2e978a8c 704 my ($self, $c, $obj) = @_;
d2739840 705
b421ef50 706 my ($object, $params) = @$obj;
707
708 if ($object->in_storage)
d2739840 709 {
2e978a8c 710 $self->update_object_from_params($c, $object, $params);
b421ef50 711 }
406086f3 712 else
b421ef50 713 {
2e978a8c 714 $self->insert_object_from_params($c, $object, $params);
b421ef50 715 }
716
717}
718
719=method_protected update_object_from_params
720
721update_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 ->upbdate on the object.
722
723=cut
724
725sub update_object_from_params
726{
2e978a8c 727 my ($self, $c, $object, $params) = @_;
b421ef50 728
729 foreach my $key (keys %$params)
730 {
731 my $value = $params->{$key};
732 if (ref($value) && !($value == JSON::Any::true || $value == JSON::Any::false))
733 {
2e978a8c 734 $self->update_object_relation($c, $object, delete $params->{$key}, $key);
d2739840 735 }
736 }
406086f3 737
b421ef50 738 $object->update($params);
739}
740
741=method_protected update_object_relation
742
743update_object_relation finds the relation to the object, then calls ->update with the specified parameters
744
745=cut
746
747sub update_object_relation
748{
2e978a8c 749 my ($self, $c, $object, $related_params, $relation) = @_;
b421ef50 750 my $row = $object->find_related($relation, {} , {});
8516bd76 751
752 if ($row) {
753 $row->update($related_params);
754 }
755 else {
756 $object->create_related($relation, $related_params);
757 }
b421ef50 758}
759
760=method_protected insert_object_from_params
761
762insert_object_from_params sets the columns for the object, then calls ->insert
763
764=cut
765
766sub insert_object_from_params
767{
2e978a8c 768 my ($self, $c, $object, $params) = @_;
b421ef50 769 $object->set_columns($params);
770 $object->insert;
d2739840 771}
772
b421ef50 773=method_protected delete_objects
774
775delete_objects iterates through each object calling L</delete_object>
776
777=cut
778
d2739840 779sub delete_objects
780{
2e978a8c 781 my ($self, $c, $objects) = @_;
b421ef50 782
2e978a8c 783 map { $self->delete_object($c, $_->[0]) } @$objects;
b421ef50 784}
785
786=method_protected delete_object
787
788Performs the actual ->delete on the object
789
790=cut
791
792sub delete_object
793{
2e978a8c 794 my ($self, $c, $object) = @_;
d2739840 795
b421ef50 796 $object->delete;
d2739840 797}
798
799=method_protected end
800
d2739840 801end 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
802
803=cut
804
3d85db11 805sub end :Private
d2739840 806{
d2739840 807 my ($self, $c) = @_;
808
809 # check for errors
810 my $default_status;
811
812 # Check for errors caught elsewhere
813 if ( $c->res->status and $c->res->status != 200 ) {
814 $default_status = $c->res->status;
815 $c->stash->{response}->{success} = $self->use_json_boolean ? JSON::Any::false : 'false';
816 } elsif ($self->get_errors($c)) {
817 $c->stash->{response}->{messages} = $self->get_errors($c);
818 $c->stash->{response}->{success} = $self->use_json_boolean ? JSON::Any::false : 'false';
819 $default_status = 400;
820 } else {
821 $c->stash->{response}->{success} = $self->use_json_boolean ? JSON::Any::true : 'true';
822 $default_status = 200;
823 }
406086f3 824
d2739840 825 unless ($default_status == 200)
826 {
827 delete $c->stash->{response}->{$self->data_root};
828 }
829 elsif($self->return_object && $c->req->has_objects)
830 {
d2739840 831 my $returned_objects = [];
c9b8a798 832 push(@$returned_objects, $self->each_object_inflate($c, $_)) for map { $_->[0] } $c->req->all_objects;
d2739840 833 $c->stash->{response}->{$self->data_root} = scalar(@$returned_objects) > 1 ? $returned_objects : $returned_objects->[0];
834 }
835
836 $c->res->status( $default_status || 200 );
837 $c->forward('serialize');
838}
839
c9b8a798 840=method_protected each_object_inflate
841
842each_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.
843
844This only executes if L</return_object> if set and if there are any objects to actually return.
845
846=cut
847
848sub each_object_inflate
849{
850 my ($self, $c, $object) = @_;
d2739840 851
c9b8a798 852 return { $object->get_inflated_columns };
d2739840 853}
854
c9b8a798 855# from Catalyst::Action::Serialize
856sub serialize :ActionClass('Serialize') { }
857
d2739840 858=method_protected push_error
859
860push_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.
861
862=cut
863
864sub push_error
865{
866 my ( $self, $c, $params ) = @_;
867 push( @{$c->stash->{_dbic_crud_errors}}, $params->{message} || 'unknown error' );
868}
869
870=method_protected get_errors
871
872get_errors returns all of the errors stored in the stash
873
874=cut
875
876sub get_errors
877{
878 my ( $self, $c ) = @_;
879 return $c->stash->{_dbic_crud_errors};
880}
881
882=head1 DESCRIPTION
883
884Easily 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.
885
886=head1 OVERVIEW
887
888This 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.
889
890You 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>.
891
892Also 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.
893
894=head2 CONFIGURATION
895
896Each 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>.
897
898The class, create_requires, create_allows and update_requires parameters can also be set in the stash like so:
899
900 sub setup :Chained('/api/rpc/rpc_base') :CaptureArgs(1) :PathPart('any') {
901 my ($self, $c, $object_type) = @_;
902
903 if ($object_type eq 'artist') {
904 $c->stash->{class} = 'MyAppDB::Artist';
905 $c->stash->{create_requires} = [qw/name/];
906 $c->stash->{update_allows} = [qw/name/];
907 } else {
908 $self->push_error($c, { message => "invalid object_type" });
909 return;
910 }
911
912 $self->next::method($c);
913 }
914
915Generally it's better to have one controller for each DBIC source with the config hardcoded, but in some cases this isn't possible.
916
917Note 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.
918
919Below are explanations for various configuration parameters. Please see L<Catalyst::Controller::DBIC::API::StaticArguments> for more details.
920
921=head3 class
922
923Whatever you would pass to $c->model to get a resultset for this class. MyAppDB::Track for example.
924
925=head3 data_root
926
927By 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.
928
929=head3 use_json_boolean
930
931By 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.
932
933=head3 count_arg, page_arg, select_arg, search_arg, grouped_by_arg, ordered_by_arg, prefetch_arg, as_arg, total_entries_arg
934
935These 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.
936
937=head3 create_requires
938
939Arrayref listing columns required to be passed to create in order for the request to be valid.
940
941=head3 create_allows
942
943Arrayref 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.
944
945=head3 update_allows
946
947Arrayref listing columns that update will allow. Columns passed to update that are not listed here will be ignored.
948
949=head3 select
950
951Arguments to pass to L<DBIx::Class::ResultSet/select> when performing search for L</list>.
952
953=head3 as
954
955Complements 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.
956
957=head3 select_exposes
958
959Columns 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.
960
961=head3 prefetch
962
963Arguments to pass to L<DBIx::Class::ResultSet/prefetch> when performing search for L</list>.
964
965=head3 prefetch_allows
966
967Arrayref listing relationships that are allowed to be prefetched.
968This is necessary to avoid denial of service attacks in form of
969queries which would return a large number of data
970and unwanted disclosure of data.
971
972=head3 grouped_by
973
974Arguments to pass to L<DBIx::Class::ResultSet/group_by> when performing search for L</list>.
975
976=head3 ordered_by
977
978Arguments to pass to L<DBIx::Class::ResultSet/order_by> when performing search for L</list>.
979
980=head3 search_exposes
981
982Columns and related columns that are okay to search on. For example if only the position column and all cd columns were to be allowed
983
984 search_exposes => [qw/position/, { cd => ['*'] }]
985
986You 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:
987
988 package RestTest::Controller::API::RPC::TrackExposed;
406086f3 989
d2739840 990 ...
406086f3 991
d2739840 992 __PACKAGE__->config
993 ( ...,
994 search_exposes => [qw/position title custom_column/],
995 );
996
997and then in your custom resultset:
998
999 package RestTest::Schema::ResultSet::Track;
406086f3 1000
d2739840 1001 use base 'RestTest::Schema::ResultSet';
406086f3 1002
d2739840 1003 sub search {
1004 my $self = shift;
1005 my ($clause, $params) = @_;
1006
1007 # test custom attrs
1008 if (my $pretend = delete $clause->{custom_column}) {
1009 $clause->{'cd.year'} = $pretend;
1010 }
1011 my $rs = $self->SUPER::search(@_);
1012 }
1013
1014=head3 count
1015
1016Arguments to pass to L<DBIx::Class::ResultSet/rows> when performing search for L</list>.
1017
1018=head3 page
1019
1020Arguments to pass to L<DBIx::Class::ResultSet/rows> when performing search for L</list>.
1021
1022=head1 EXTENDING
1023
1024By 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.
1025
1026For example if you wanted create to return the JSON for the newly created object you might have something like:
1027
1028 package MyApp::ControllerBase::DBIC::API::RPC;
1029 ...
1030 use Moose;
1031 BEGIN { extends 'Catalyst::Controller::DBIC::API::RPC' };
1032 ...
1033 sub create :Chained('setup') :Args(0) :PathPart('create') {
1034 my ($self, $c) = @_;
1035
1036 # $c->req->all_objects will contain all of the created
1037 $self->next::method($c);
1038
406086f3 1039 if ($c->req->has_objects) {
d2739840 1040 # $c->stash->{response} will be serialized in the end action
1041 $c->stash->{response}->{$self->data_root} = [ map { { $_->get_inflated_columns } } ($c->req->all_objects) ] ;
1042 }
1043 }
1044
d2739840 1045 package MyApp::Controller::API::RPC::Track;
1046 ...
1047 use Moose;
1048 BEGIN { extends 'MyApp::ControllerBase::DBIC::API::RPC' };
1049 ...
1050
d666a194 1051It should be noted that the return_object attribute will produce the above result for you, free of charge.
d2739840 1052
d2739840 1053Similarly 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.
1054
406086f3 1055If more extensive customization is required, it is recommened to peer into the roles that comprise the system and make use
d2739840 1056
1057=head1 NOTES
1058
1059It 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.
1060
1061To 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.
1062
1063Validation 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>.
1064
1065Since 2.00100:
1066Transactions are used. The stash is put aside in favor of roles applied to the request object with additional accessors.
1067Error handling is now much more consistent with most errors immediately detaching.
1068The internals are much easier to read and understand with lots more documentation.
1069
1070=cut
1071
10721;