lib/Catalyst/Controller/DBIC/API.pm

   1 package Catalyst::Controller::DBIC::API;
   2
   3 #ABSTRACT: Provides a DBIx::Class web service automagically
   4 use Moose;
   5 BEGIN { extends 'Catalyst::Controller'; }
   6
   7 use CGI::Expand ();
   8 use DBIx::Class::ResultClass::HashRefInflator;
   9 use JSON ();
  10 use Test::Deep::NoTest('eq_deeply');
  11 use MooseX::Types::Moose(':all');
  12 use Moose::Util;
  13 use Scalar::Util( 'blessed', 'reftype' );
  14 use Try::Tiny;
  15 use Catalyst::Controller::DBIC::API::Request;
  16 use namespace::autoclean;
  17
  18 has '_json' => (
  19     is         => 'ro',
  20     isa        => 'JSON',
  21     lazy_build => 1,
  22 );
  23
  24 sub _build__json {
  25
  26     # no ->utf8 here because the request params get decoded by Catalyst
  27     return JSON->new;
  28 }
  29
  30 with 'Catalyst::Controller::DBIC::API::StoredResultSource',
  31     'Catalyst::Controller::DBIC::API::StaticArguments';
  32
  33 with 'Catalyst::Controller::DBIC::API::RequestArguments' => { static => 1 };
  34
  35 __PACKAGE__->config();
  36
  37 =head1 SYNOPSIS
  38
  39   package MyApp::Controller::API::RPC::Artist;
  40   use Moose;
  41   BEGIN { extends 'Catalyst::Controller::DBIC::API::RPC' }
  42
  43   __PACKAGE__->config
  44     ( # define parent chain action and PathPart
  45       action => {
  46           setup => {
  47               Chained  => '/api/rpc/rpc_base',
  48               PathPart => 'artist',
  49           }
  50       },
  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'],
  58       prefetch         => ['cds'],
  59       prefetch_allows  => [
  60           'cds',
  61           { cds => 'tracks' },
  62           { cds => ['tracks'] },
  63       ],
  64       ordered_by       => ['age'],
  65       search_exposes   => ['age', 'nickname', { cds => ['title', 'year'] }],
  66       data_root        => 'data',
  67       use_json_boolean => 1,
  68       return_object    => 1,
  69       );
  70
  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
  76 =cut
  77
  78 =method_private begin
  79
  80  :Private
  81
  82 begin is provided in the base class to setup the Catalyst Request object, by applying the DBIC::API::Request role.
  83
  84 =cut
  85
  86 sub begin : Private {
  87     my ( $self, $c ) = @_;
  88
  89     Moose::Util::ensure_all_roles( $c->req,
  90         'Catalyst::Controller::DBIC::API::Request' );
  91 }
  92
  93 =method_protected setup
  94
  95  :Chained('specify.in.subclass.config') :CaptureArgs(0) :PathPart('specify.in.subclass.config')
  96
  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
 100
 101   package MyApp::Controller::API::RPC::Track;
 102   use Moose;
 103   BEGIN { extends 'Catalyst::Controller::DBIC::API::RPC'; }
 104
 105   __PACKAGE__->config
 106     ( action => { setup => { PathPart => 'track', Chained => '/api/rpc/rpc_base' } },
 107         ...
 108   );
 109
 110   # or
 111
 112   sub setup :Chained('/api/rpc/rpc_base') :CaptureArgs(0) :PathPart('track') {
 113     my ($self, $c) = @_;
 114
 115     $self->next::method($c);
 116   }
 117
 118 This action does nothing by default.
 119
 120 =cut
 121
 122 sub setup : Chained('specify.in.subclass.config') : CaptureArgs(0) :
 123     PathPart('specify.in.subclass.config') { }
 124
 125 =method_protected deserialize
 126
 127  :Chained('setup') :CaptureArgs(0) :PathPart('') :ActionClass('Deserialize')
 128
 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:
 130
 131     search_arg
 132     count_arg
 133     page_arg
 134     ordered_by_arg
 135     grouped_by_arg
 136     prefetch_arg
 137
 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.
 139
 140 =cut
 141
 142 sub deserialize : Chained('setup') : CaptureArgs(0) : PathPart('') :
 143     ActionClass('Deserialize') {
 144     my ( $self, $c ) = @_;
 145     my $req_params;
 146
 147     if ( $c->req->data && scalar( keys %{ $c->req->data } ) ) {
 148         $req_params = $c->req->data;
 149     }
 150     else {
 151         $req_params = CGI::Expand->expand_hash( $c->req->params );
 152
 153         foreach my $param (
 154             @{  [   $self->search_arg,     $self->count_arg,
 155                     $self->page_arg,       $self->offset_arg,
 156                     $self->ordered_by_arg, $self->grouped_by_arg,
 157                     $self->prefetch_arg
 158                 ]
 159             }
 160             )
 161         {
 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};
 165
 166             # find out if CGI::Expand was involved
 167             if ( ref $req_params->{$param} eq 'HASH' ) {
 168                 for my $key ( keys %{ $req_params->{$param} } ) {
 169
 170                     # copy the value because JSON::XS will alter it
 171                     # even if decoding failed
 172                     my $value = $req_params->{$param}->{$key};
 173                     try {
 174                         my $deserialized = $self->_json->decode($value);
 175                         $req_params->{$param}->{$key} = $deserialized;
 176                     }
 177                     catch {
 178                         $c->log->debug(
 179                             "Param '$param.$key' did not deserialize appropriately: $_"
 180                         ) if $c->debug;
 181                     }
 182                 }
 183             }
 184             else {
 185                 try {
 186                     my $value        = $req_params->{$param};
 187                     my $deserialized = $self->_json->decode($value);
 188                     $req_params->{$param} = $deserialized;
 189                 }
 190                 catch {
 191                     $c->log->debug(
 192                         "Param '$param' did not deserialize appropriately: $_"
 193                     ) if $c->debug;
 194                 }
 195             }
 196         }
 197     }
 198
 199     $self->inflate_request( $c, $req_params );
 200 }
 201
 202 =method_protected generate_rs
 203
 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
 208 getting a resultset.
 209
 210 =cut
 211
 212 sub generate_rs {
 213     my ( $self, $c ) = @_;
 214
 215     return $c->model( $c->stash->{class} || $self->class );
 216 }
 217
 218 =method_protected inflate_request
 219
 220 inflate_request is called at the end of deserialize to populate key portions of the request with the useful bits
 221
 222 =cut
 223
 224 sub inflate_request {
 225     my ( $self, $c, $params ) = @_;
 226
 227     try {
 228         # set static arguments
 229         $c->req->_set_controller($self);
 230
 231         # set request arguments
 232         $c->req->_set_request_data($params);
 233
 234         # set the current resultset
 235         $c->req->_set_current_result_set( $self->generate_rs($c) );
 236
 237     }
 238     catch {
 239         $c->log->error($_);
 240         $self->push_error( $c, { message => $_ } );
 241         $c->detach();
 242     }
 243 }
 244
 245 =method_protected object_with_id
 246
 247  :Chained('deserialize') :CaptureArgs(1) :PathPart('')
 248
 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.
 250
 251 =cut
 252
 253 sub object_with_id : Chained('deserialize') : CaptureArgs(1) : PathPart('') {
 254     my ( $self, $c, $id ) = @_;
 255
 256     my $vals = $c->req->request_data->{ $self->data_root };
 257     unless ( defined($vals) ) {
 258
 259         # no data root, assume the request_data itself is the payload
 260         $vals = $c->req->request_data;
 261     }
 262
 263     try {
 264         # there can be only one set of data
 265         $c->req->add_object( [ $self->object_lookup( $c, $id ), $vals ] );
 266     }
 267     catch {
 268         $c->log->error($_);
 269         $self->push_error( $c, { message => $_ } );
 270         $c->detach();
 271     }
 272 }
 273
 274 =method_protected objects_no_id
 275
 276  :Chained('deserialize') :CaptureArgs(0) :PathPart('')
 277
 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.
 279
 280 =cut
 281
 282 sub objects_no_id : Chained('deserialize') : CaptureArgs(0) : PathPart('') {
 283     my ( $self, $c ) = @_;
 284
 285     if ( $c->req->has_request_data ) {
 286         my $data = $c->req->request_data;
 287         my $vals;
 288
 289         if ( exists( $data->{ $self->data_root } )
 290             && defined( $data->{ $self->data_root } ) )
 291         {
 292             my $root = $data->{ $self->data_root };
 293             if ( reftype($root) eq 'ARRAY' ) {
 294                 $vals = $root;
 295             }
 296             elsif ( reftype($root) eq 'HASH' ) {
 297                 $vals = [$root];
 298             }
 299             else {
 300                 $c->log->error('Invalid request data');
 301                 $self->push_error( $c,
 302                     { message => 'Invalid request data' } );
 303                 $c->detach();
 304             }
 305         }
 306         else {
 307             # no data root, assume the request_data itself is the payload
 308             $vals = [ $c->req->request_data ];
 309         }
 310
 311         foreach my $val (@$vals) {
 312             unless ( exists( $val->{id} ) ) {
 313                 $c->req->add_object(
 314                     [ $c->req->current_result_set->new_result( {} ), $val ] );
 315                 next;
 316             }
 317
 318             try {
 319                 $c->req->add_object(
 320                     [ $self->object_lookup( $c, $val->{id} ), $val ] );
 321             }
 322             catch {
 323                 $c->log->error($_);
 324                 $self->push_error( $c, { message => $_ } );
 325                 $c->detach();
 326             }
 327         }
 328     }
 329 }
 330
 331 =method_protected object_lookup
 332
 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.
 334
 335 =cut
 336
 337 sub object_lookup {
 338     my ( $self, $c, $id ) = @_;
 339
 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;
 343     return $object;
 344 }
 345
 346 =method_protected list
 347
 348 list's steps are broken up into three distinct methods: L</list_munge_parameters>, L</list_perform_search>, and L</list_format_output>.
 349
 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.
 351
 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.
 353
 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.
 355
 356 For example, these request parameters:
 357
 358  ?search.name=fred&search.cd.artist=luke
 359  OR
 360  ?search={"name":"fred","cd": {"artist":"luke"}}
 361
 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):
 363
 364  $rs->search({ name => 'fred', 'cd.artist' => 'luke' }, { join => ['cd'] })
 365
 366 It is also possible to use a JSON string for expandeded parameters:
 367
 368  ?search.datetime={"-between":["2010-01-06 19:28:00","2010-01-07 19:28:00"]}
 369
 370 Note that if pagination is needed, this can be achieved using a combination of the L</count> and L</page> parameters. For example:
 371
 372   ?page=2&count=20
 373
 374 Would result in this search:
 375
 376  $rs->search({}, { page => 2, rows => 20 })
 377
 378 =cut
 379
 380 sub list {
 381     my ( $self, $c ) = @_;
 382
 383     $self->list_munge_parameters($c);
 384     $self->list_perform_search($c);
 385     $self->list_format_output($c);
 386
 387     # make sure there are no objects lingering
 388     $c->req->clear_objects();
 389 }
 390
 391 =method_protected list_munge_parameters
 392
 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).
 395
 396 =cut
 397
 398 sub list_munge_parameters { }    # noop by default
 399
 400 =method_protected list_perform_search
 401
 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.
 403
 404 =cut
 405
 406 sub list_perform_search {
 407     my ( $self, $c ) = @_;
 408
 409     try {
 410         my $req = $c->req;
 411
 412         my $rs =
 413             $req->current_result_set->search( $req->search_parameters,
 414             $req->search_attributes );
 415
 416         $req->_set_current_result_set($rs);
 417
 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} ) );
 424     }
 425     catch {
 426         $c->log->error($_);
 427         $self->push_error( $c,
 428             { message => 'a database error has occured.' } );
 429         $c->detach();
 430     }
 431 }
 432
 433 =method_protected list_format_output
 434
 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.
 436
 437 =cut
 438
 439 sub list_format_output {
 440     my ( $self, $c ) = @_;
 441
 442     my $rs = $c->req->current_result_set->search;
 443     $rs->result_class( $self->result_class ) if $self->result_class;
 444
 445     try {
 446         my $output    = {};
 447         my $formatted = [];
 448
 449         foreach my $row ( $rs->all ) {
 450             push( @$formatted, $self->row_format_output( $c, $row ) );
 451         }
 452
 453         $output->{ $self->data_root } = $formatted;
 454
 455         if ( $c->req->has_search_total_entries ) {
 456             $output->{ $self->total_entries_arg } =
 457                 $c->req->search_total_entries + 0;
 458         }
 459
 460         $c->stash->{ $self->stash_key } = $output;
 461     }
 462     catch {
 463         $c->log->error($_);
 464         $self->push_error( $c,
 465             { message => 'a database error has occured.' } );
 466         $c->detach();
 467     }
 468 }
 469
 470 =method_protected row_format_output
 471
 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.
 473
 474 =cut
 475
 476 sub row_format_output {
 477
 478     #my ($self, $c, $row) = @_;
 479     my ( $self, undef, $row ) = @_;
 480     return $row;    # passthrough by default
 481 }
 482
 483 =method_protected item
 484
 485 item will return a single object called by identifier in the uri. It will be inflated via each_object_inflate.
 486
 487 =cut
 488
 489 sub item {
 490     my ( $self, $c ) = @_;
 491
 492     if ( $c->req->count_objects != 1 ) {
 493         $c->log->error($_);
 494         $self->push_error( $c,
 495             { message => 'No objects on which to operate' } );
 496         $c->detach();
 497     }
 498     else {
 499         $c->stash->{ $self->stash_key }->{ $self->item_root } =
 500             $self->each_object_inflate( $c, $c->req->get_object(0)->[0] );
 501     }
 502 }
 503
 504 =method_protected update_or_create
 505
 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>.
 507
 508 =cut
 509
 510 sub update_or_create {
 511     my ( $self, $c ) = @_;
 512
 513     if ( $c->req->has_objects ) {
 514         $self->validate_objects($c);
 515         $self->transact_objects( $c, sub { $self->save_objects( $c, @_ ) } );
 516     }
 517     else {
 518         $c->log->error($_);
 519         $self->push_error( $c,
 520             { message => 'No objects on which to operate' } );
 521         $c->detach();
 522     }
 523 }
 524
 525 =method_protected transact_objects
 526
 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.
 528
 529 =cut
 530
 531 sub transact_objects {
 532     my ( $self, $c, $coderef ) = @_;
 533
 534     try {
 535         $self->stored_result_source->schema->txn_do( $coderef,
 536             $c->req->objects );
 537     }
 538     catch {
 539         $c->log->error($_);
 540         $self->push_error( $c,
 541             { message => 'a database error has occured.' } );
 542         $c->detach();
 543     }
 544 }
 545
 546 =method_protected validate_objects
 547
 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.
 549
 550 =cut
 551
 552 sub validate_objects {
 553     my ( $self, $c ) = @_;
 554
 555     try {
 556         foreach my $obj ( $c->req->all_objects ) {
 557             $obj->[1] = $self->validate_object( $c, $obj );
 558         }
 559     }
 560     catch {
 561         my $err = $_;
 562         $c->log->error($err);
 563         $err =~ s/\s+at\s+.+\n$//g;
 564         $self->push_error( $c, { message => $err } );
 565         $c->detach();
 566     }
 567 }
 568
 569 =method_protected validate_object
 570
 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.
 572
 573 =cut
 574
 575 sub validate_object {
 576     my ( $self, $c, $obj ) = @_;
 577     my ( $object, $params ) = @$obj;
 578
 579     my %values;
 580     my %requires_map = map { $_ => 1 } @{
 581           ( $object->in_storage )
 582         ? []
 583         : $c->stash->{create_requires} || $self->create_requires
 584     };
 585
 586     my %allows_map = map { ( ref $_ ) ? %{$_} : ( $_ => 1 ) } (
 587         keys %requires_map,
 588         @{    ( $object->in_storage )
 589             ? ( $c->stash->{update_allows} || $self->update_allows )
 590             : ( $c->stash->{create_allows} || $self->create_allows )
 591         }
 592     );
 593
 594     foreach my $key ( keys %allows_map ) {
 595
 596         # check value defined if key required
 597         my $allowed_fields = $allows_map{$key};
 598
 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 ]
 606                 : $allowed_fields;
 607
 608             foreach my $related_col ( @{$allowed_related_cols} ) {
 609                 if (defined(
 610                         my $related_col_value =
 611                             $related_params->{$related_col}
 612                     )
 613                     )
 614                 {
 615                     $values{$key}{$related_col} = $related_col_value;
 616                 }
 617             }
 618         }
 619         else {
 620             my $value = $params->{$key};
 621
 622             if ( $requires_map{$key} ) {
 623                 unless ( defined($value) ) {
 624
 625                     # if not defined look for default
 626                     $value = $object->result_source->column_info($key)
 627                         ->{default_value};
 628                     unless ( defined $value ) {
 629                         die "No value supplied for ${key} and no default";
 630                     }
 631                 }
 632             }
 633
 634             # check for multiple values
 635             if ( ref($value) && !( reftype($value) eq reftype(JSON::true) ) )
 636             {
 637                 require Data::Dumper;
 638                 die
 639                     "Multiple values for '${key}': ${\Data::Dumper::Dumper($value)}";
 640             }
 641
 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;
 646         }
 647     }
 648
 649     unless ( keys %values || !$object->in_storage ) {
 650         die 'No valid keys passed';
 651     }
 652
 653     return \%values;
 654 }
 655
 656 =method_protected delete
 657
 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.
 659
 660 =cut
 661
 662 sub delete {
 663     my ( $self, $c ) = @_;
 664
 665     if ( $c->req->has_objects ) {
 666         $self->transact_objects( $c,
 667             sub { $self->delete_objects( $c, @_ ) } );
 668         $c->req->clear_objects;
 669     }
 670     else {
 671         $c->log->error($_);
 672         $self->push_error( $c,
 673             { message => 'No objects on which to operate' } );
 674         $c->detach();
 675     }
 676 }
 677
 678 =method_protected save_objects
 679
 680 This method is used by update_or_create to perform the actual database manipulations. It iterates each object calling L</save_object>.
 681
 682 =cut
 683
 684 sub save_objects {
 685     my ( $self, $c, $objects ) = @_;
 686
 687     foreach my $obj (@$objects) {
 688         $self->save_object( $c, $obj );
 689     }
 690 }
 691
 692 =method_protected save_object
 693
 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>
 695
 696 =cut
 697
 698 sub save_object {
 699     my ( $self, $c, $obj ) = @_;
 700
 701     my ( $object, $params ) = @$obj;
 702
 703     if ( $object->in_storage ) {
 704         $self->update_object_from_params( $c, $object, $params );
 705     }
 706     else {
 707         $self->insert_object_from_params( $c, $object, $params );
 708     }
 709
 710 }
 711
 712 =method_protected update_object_from_params
 713
 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.
 715
 716 =cut
 717
 718 sub update_object_from_params {
 719     my ( $self, $c, $object, $params ) = @_;
 720
 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 );
 726         }
 727
 728         # accessor = colname
 729         elsif ( $object->can($key) ) {
 730             $object->$key($value);
 731         }
 732
 733         # accessor != colname
 734         else {
 735             my $accessor =
 736                 $object->result_source->column_info($key)->{accessor};
 737             $object->$accessor($value);
 738         }
 739     }
 740
 741     $object->update();
 742 }
 743
 744 =method_protected update_object_relation
 745
 746 update_object_relation finds the relation to the object, then calls ->update with the specified parameters
 747
 748 =cut
 749
 750 sub update_object_relation {
 751     my ( $self, $c, $object, $related_params, $relation ) = @_;
 752     my $row = $object->find_related( $relation, {}, {} );
 753
 754     if ($row) {
 755         foreach my $key ( keys %$related_params ) {
 756             my $value = $related_params->{$key};
 757             if ( ref($value) && !( reftype($value) eq reftype(JSON::true) ) )
 758             {
 759                 $self->update_object_relation( $c, $row,
 760                     delete $related_params->{$key}, $key );
 761             }
 762
 763             # accessor = colname
 764             elsif ( $row->can($key) ) {
 765                 $row->$key($value);
 766             }
 767
 768             # accessor != colname
 769             else {
 770                 my $accessor =
 771                     $row->result_source->column_info($key)->{accessor};
 772                 $row->$accessor($value);
 773             }
 774         }
 775         $row->update();
 776     }
 777     else {
 778         $object->create_related( $relation, $related_params );
 779     }
 780 }
 781
 782 =method_protected insert_object_from_params
 783
 784 insert_object_from_params sets the columns for the object, then calls ->insert
 785
 786 =cut
 787
 788 sub insert_object_from_params {
 789
 790     #my ($self, $c, $object, $params) = @_;
 791     my ( $self, undef, $object, $params ) = @_;
 792
 793     my %rels;
 794     while ( my ( $key, $value ) = each %{$params} ) {
 795         if ( ref($value) && !( reftype($value) eq reftype(JSON::true) ) ) {
 796             $rels{$key} = $value;
 797         }
 798
 799         # accessor = colname
 800         elsif ( $object->can($key) ) {
 801             $object->$key($value);
 802         }
 803
 804         # accessor != colname
 805         else {
 806             my $accessor =
 807                 $object->result_source->column_info($key)->{accessor};
 808             $object->$accessor($value);
 809         }
 810     }
 811
 812     $object->insert;
 813
 814     while ( my ( $k, $v ) = each %rels ) {
 815         $object->create_related( $k, $v );
 816     }
 817 }
 818
 819 =method_protected delete_objects
 820
 821 delete_objects iterates through each object calling L</delete_object>
 822
 823 =cut
 824
 825 sub delete_objects {
 826     my ( $self, $c, $objects ) = @_;
 827
 828     map { $self->delete_object( $c, $_->[0] ) } @$objects;
 829 }
 830
 831 =method_protected delete_object
 832
 833 Performs the actual ->delete on the object
 834
 835 =cut
 836
 837 sub delete_object {
 838
 839     #my ($self, $c, $object) = @_;
 840     my ( $self, undef, $object ) = @_;
 841
 842     $object->delete;
 843 }
 844
 845 =method_protected end
 846
 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
 848
 849 =cut
 850
 851 sub end : Private {
 852     my ( $self, $c ) = @_;
 853
 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);
 858         }
 859         else {
 860             $c->res->status(200);
 861         }
 862     }
 863
 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
 873                 ? $returned_objects
 874                 : $returned_objects->[0];
 875         }
 876     }
 877     else {
 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);
 882
 883         # don't return data for error responses
 884         delete $c->stash->{ $self->stash_key }->{ $self->data_root };
 885     }
 886
 887     $c->forward('serialize');
 888 }
 889
 890 =method_protected each_object_inflate
 891
 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.
 893
 894 This only executes if L</return_object> if set and if there are any objects to actually return.
 895
 896 =cut
 897
 898 sub each_object_inflate {
 899
 900     #my ($self, $c, $object) = @_;
 901     my ( $self, undef, $object ) = @_;
 902
 903     return { $object->get_columns };
 904 }
 905
 906 =method_protected serialize
 907
 908 multiple actions forward to serialize which uses Catalyst::Action::Serialize.
 909
 910 =cut
 911
 912 # from Catalyst::Action::Serialize
 913 sub serialize : ActionClass('Serialize') { }
 914
 915 =method_protected push_error
 916
 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.
 918
 919 =cut
 920
 921 sub push_error {
 922     my ( $self, $c, $params ) = @_;
 923     die 'Catalyst app object missing'
 924         unless defined $c;
 925     my $error = 'unknown error';
 926     if ( exists $params->{message} ) {
 927         $error = $params->{message};
 928
 929         # remove newline from die "error message\n" which is required to not
 930         # have the filename and line number in the error text
 931         $error =~ s/\n$//;
 932     }
 933     push( @{ $c->stash->{_dbic_crud_errors} }, $error );
 934 }
 935
 936 =method_protected get_errors
 937
 938 get_errors returns all of the errors stored in the stash
 939
 940 =cut
 941
 942 sub get_errors {
 943     my ( $self, $c ) = @_;
 944     die 'Catalyst app object missing'
 945         unless defined $c;
 946     return $c->stash->{_dbic_crud_errors};
 947 }
 948
 949 =method_protected has_errors
 950
 951 returns returns true if errors are stored in the stash
 952
 953 =cut
 954
 955 sub has_errors {
 956     my ( $self, $c ) = @_;
 957     die 'Catalyst app object missing'
 958         unless defined $c;
 959     return exists $c->stash->{_dbic_crud_errors};
 960 }
 961
 962 =head1 DESCRIPTION
 963
 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.
 965
 966 =head1 OVERVIEW
 967
 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.
 969
 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>.
 971
 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.
 973
 974 =head2 CONFIGURATION
 975
 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>.
 977
 978 The class, create_requires, create_allows and update_requires parameters can also be set in the stash like so:
 979
 980   sub setup :Chained('/api/rpc/rpc_base') :CaptureArgs(1) :PathPart('any') {
 981     my ($self, $c, $object_type) = @_;
 982
 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/];
 987     } else {
 988       $self->push_error($c, { message => "invalid object_type" });
 989       return;
 990     }
 991
 992     $self->next::method($c);
 993   }
 994
 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.
 996
 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.
 998
 999 Below are explanations for various configuration parameters. Please see L<Catalyst::Controller::DBIC::API::StaticArguments> for more details.
1000
1001 =head3 class
1002
1003 Whatever you would pass to $c->model to get a resultset for this class. MyAppDB::Track for example.
1004
1005 =head3 resultset_class
1006
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.
1008
1009 =head3 stash_key
1010
1011 Controls where in stash request_data should be stored, and defaults to 'response'.
1012
1013 =head3 data_root
1014
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.
1016
1017 =head3 use_json_boolean
1018
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.
1020
1021 =head3 count_arg, page_arg, select_arg, search_arg, grouped_by_arg, ordered_by_arg, prefetch_arg, as_arg, total_entries_arg
1022
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.
1024
1025 =head3 create_requires
1026
1027 Arrayref listing columns required to be passed to create in order for the request to be valid.
1028
1029 =head3 create_allows
1030
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.
1032
1033 =head3 update_allows
1034
1035 Arrayref listing columns that update will allow. Columns passed to update that are not listed here will be ignored.
1036
1037 =head3 select
1038
1039 Arguments to pass to L<DBIx::Class::ResultSet/select> when performing search for L</list>.
1040
1041 =head3 as
1042
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.
1044
1045 =head3 select_exposes
1046
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.
1048
1049 =head3 prefetch
1050
1051 Arguments to pass to L<DBIx::Class::ResultSet/prefetch> when performing search for L</list>.
1052
1053 =head3 prefetch_allows
1054
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.
1059
1060 =head3 grouped_by
1061
1062 Arguments to pass to L<DBIx::Class::ResultSet/group_by> when performing search for L</list>.
1063
1064 =head3 ordered_by
1065
1066 Arguments to pass to L<DBIx::Class::ResultSet/order_by> when performing search for L</list>.
1067
1068 =head3 search_exposes
1069
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
1071
1072  search_exposes => [qw/position/, { cd => ['*'] }]
1073
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:
1075
1076   package RestTest::Controller::API::RPC::TrackExposed;
1077
1078   ...
1079
1080   __PACKAGE__->config
1081     ( ...,
1082       search_exposes => [qw/position title custom_column/],
1083     );
1084
1085 and then in your custom resultset:
1086
1087   package RestTest::Schema::ResultSet::Track;
1088
1089   use base 'RestTest::Schema::ResultSet';
1090
1091   sub search {
1092     my $self = shift;
1093     my ($clause, $params) = @_;
1094
1095     # test custom attrs
1096     if (my $pretend = delete $clause->{custom_column}) {
1097       $clause->{'cd.year'} = $pretend;
1098     }
1099     my $rs = $self->SUPER::search(@_);
1100   }
1101
1102 =head3 count
1103
1104 Arguments to pass to L<DBIx::Class::ResultSet/rows> when performing search for L</list>.
1105
1106 =head3 page
1107
1108 Arguments to pass to L<DBIx::Class::ResultSet/page> when performing search for L</list>.
1109
1110 =head1 EXTENDING
1111
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.
1113
1114 For example if you wanted create to return the JSON for the newly created object you might have something like:
1115
1116   package MyApp::ControllerBase::DBIC::API::RPC;
1117   ...
1118   use Moose;
1119   BEGIN { extends 'Catalyst::Controller::DBIC::API::RPC' };
1120   ...
1121   sub create :Chained('setup') :Args(0) :PathPart('create') {
1122     my ($self, $c) = @_;
1123
1124     # $c->req->all_objects will contain all of the created
1125     $self->next::method($c);
1126
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) ] ;
1130     }
1131   }
1132
1133   package MyApp::Controller::API::RPC::Track;
1134   ...
1135   use Moose;
1136   BEGIN { extends 'MyApp::ControllerBase::DBIC::API::RPC' };
1137   ...
1138
1139 It should be noted that the return_object attribute will produce the above result for you, free of charge.
1140
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.
1142
1143 If more extensive customization is required, it is recommened to peer into the roles that comprise the system and make use
1144
1145 =head1 NOTES
1146
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.
1148
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.
1150
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>.
1152
1153 Since 2.00100:
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.
1157
1158 =cut
1159
1160 1;