NAME
Catalyst::Controller::DBIC::API - Provides a DBIx::Class web service automagically
VERSION
version 2.007002
SYNOPSIS
package MyApp::Controller::API::RPC::Artist;
use Moose;
BEGIN { extends 'Catalyst::Controller::DBIC::API::RPC' }
__PACKAGE__->config
( # define parent chain action and PathPart
action => {
setup => {
Chained => '/api/rpc/rpc_base',
PathPart => 'artist',
}
},
class => 'MyAppDB::Artist',
resultset_class => 'MyAppDB::ResultSet::Artist',
create_requires => ['name', 'age'],
create_allows => ['nickname'],
update_allows => ['name', 'age', 'nickname'],
update_allows => ['name', 'age', 'nickname'],
select => ['name', 'age'],
prefetch => ['cds'],
prefetch_allows => [
'cds',
{ cds => 'tracks' },
{ cds => ['tracks'] },
],
ordered_by => ['age'],
search_exposes => ['age', 'nickname', { cds => ['title', 'year'] }],
data_root => 'list',
item_root => 'data',
use_json_boolean => 1,
return_object => 1,
);
# Provides the following functional endpoints:
# /api/rpc/artist/create
# /api/rpc/artist/list
# /api/rpc/artist/id/[id]/delete
# /api/rpc/artist/id/[id]/updateDESCRIPTION
Easily provide common API endpoints based on your DBIx::Class schema classes. Module provides both RPC and REST interfaces to base functionality. Uses Catalyst::Action::Serialize and Catalyst::Action::Deserialize to serialize response and/or deserialise request.
OVERVIEW
This document describes base functionlity such as list, create, delete, update and the setting of config attributes. Catalyst::Controller::DBIC::API::RPC and Catalyst::Controller::DBIC::API::REST describe details of provided endpoints to those base methods.
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 Catalyst::Controller::DBIC::API::REST. Similarly if you wanted to provide an RPC style interface then subclass Catalyst::Controller::DBIC::API::RPC. You then configure these individually as specified in "CONFIGURATION".
Also note that the test suite of this module has an example application used to run tests against. It maybe helpful to look at that until a better tutorial is written.
CONFIGURATION
Each of your controller classes needs to be configured to point at the relevant schema class, specify what can be updated and so on, as shown in the "SYNOPSIS".
The class, create_requires, create_allows and update_requires parameters can also be set in the stash like so:
sub setup :Chained('/api/rpc/rpc_base') :CaptureArgs(1) :PathPart('any') {
my ($self, $c, $object_type) = @_;
if ($object_type eq 'artist') {
$c->stash->{class} = 'MyAppDB::Artist';
$c->stash->{create_requires} = [qw/name/];
$c->stash->{update_allows} = [qw/name/];
} else {
$self->push_error($c, { message => "invalid object_type" });
return;
}
$self->next::method($c);
}Generally it's better to have one controller for each DBIC source with the config hardcoded, but in some cases this isn't possible.
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 Catalyst::DispatchType::Chained for more details.
Below are explanations for various configuration parameters. Please see Catalyst::Controller::DBIC::API::StaticArguments for more details.
class
Whatever you would pass to $c->model to get a resultset for this class. MyAppDB::Track for example.
resultset_class
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.
stash_key
Controls where in stash request_data should be stored, and defaults to 'response'.
data_root
By default, the response data of multiple item actions 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.
item_root
By default, the response data of single item actions is serialized into $c->stash->{$self->stash_key}->{$self->item_root} and item_root default to 'data'.
use_json_boolean
By default, the response success status is set to a string value of "true" or "false". If this attribute is true, JSON::MaybeXS's true() and false() will be used instead. Note, this does not effect other internal processing of boolean values.
count_arg, page_arg, select_arg, search_arg, grouped_by_arg, ordered_by_arg, prefetch_arg, as_arg, total_entries_arg
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.
create_requires
Arrayref listing columns required to be passed to create in order for the request to be valid.
create_allows
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.
update_allows
Arrayref listing columns that update will allow. Columns passed to update that are not listed here will be ignored.
select
Arguments to pass to "select" in DBIx::Class::ResultSet when performing search for "list".
as
Complements arguments passed to "select" in DBIx::Class::ResultSet when performing a search. This allows you to specify column names in the result for RDBMS functions, etc.
select_exposes
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.
prefetch
Arguments to pass to "prefetch" in DBIx::Class::ResultSet when performing search for "list".
prefetch_allows
Arrayref listing relationships that are allowed to be prefetched. This is necessary to avoid denial of service attacks in form of queries which would return a large number of data and unwanted disclosure of data.
grouped_by
Arguments to pass to "group_by" in DBIx::Class::ResultSet when performing search for "list".
ordered_by
Arguments to pass to "order_by" in DBIx::Class::ResultSet when performing search for "list".
search_exposes
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
search_exposes => [qw/position/, { cd => ['*'] }]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:
package RestTest::Controller::API::RPC::TrackExposed;
...
__PACKAGE__->config
( ...,
search_exposes => [qw/position title custom_column/],
);and then in your custom resultset:
package RestTest::Schema::ResultSet::Track;
use base 'RestTest::Schema::ResultSet';
sub search {
my $self = shift;
my ($clause, $params) = @_;
# test custom attrs
if (my $pretend = delete $clause->{custom_column}) {
$clause->{'cd.year'} = $pretend;
}
my $rs = $self->SUPER::search(@_);
}count
Arguments to pass to "rows" in DBIx::Class::ResultSet when performing search for "list".
page
Arguments to pass to "page" in DBIx::Class::ResultSet when performing search for "list".
PROTECTED_METHODS
setup
:Chained('specify.in.subclass.config') :CaptureArgs(0) :PathPart('specify.in.subclass.config')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
package MyApp::Controller::API::RPC::Track;
use Moose;
BEGIN { extends 'Catalyst::Controller::DBIC::API::RPC'; }
__PACKAGE__->config
( action => { setup => { PathPart => 'track', Chained => '/api/rpc/rpc_base' } },
...
);
# or
sub setup :Chained('/api/rpc/rpc_base') :CaptureArgs(0) :PathPart('track') {
my ($self, $c) = @_;
$self->next::method($c);
}This action does nothing by default.
deserialize
:Chained('setup') :CaptureArgs(0) :PathPart('') :ActionClass('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:
search_arg
count_arg
page_arg
ordered_by_arg
grouped_by_arg
prefetch_argIt 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.
generate_rs
generate_rs is used by inflate_request to get a resultset for the current request. It receives $c as its only argument. By default it returns a resultset of the controller's class. Override this method if you need to manipulate the default implementation of getting a resultset.
inflate_request
inflate_request is called at the end of deserialize to populate key portions of the request with the useful bits.
object_with_id
:Chained('deserialize') :CaptureArgs(1) :PathPart('')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 ofobjects.
Please see Catalyst::Controller::DBIC::API::Request::Context for more details on the stored objects.
objects_no_id
:Chained('deserialize') :CaptureArgs(0) :PathPart('')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 Catalyst::Controller::DBIC::API::Request::Context for more details on the stored objects.
object_lookup
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.
list
list's steps are broken up into three distinct methods:
The goal of this method is to call ->search() on the current_result_set, change the 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.
If the "select" config param is defined then the hashes will contain only those columns, otherwise all columns in the object will be returned. "select" of course supports the function/procedure calling semantics that "select" in DBIx::Class::ResultSet supports.
In order to have proper column names in the result, provide arguments in "as" (which also follows "as" in DBIx::Class::ResultSet semantics. Similarly "count", "page", "grouped_by" and "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, these will override the values set on the class with select becoming bound by the select_exposes attribute.
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 CGI::Expand syntax. In the second case the request parameters are expanded into a structure and then used as the search condition.
For example, these request parameters:
?search.name=fred&search.cd.artist=luke
OR
?search={"name":"fred","cd": {"artist":"luke"}}Would result in this search (where 'name' is a column of the result class, 'cd' is a relation of the result class and 'artist' is a column of the related class):
$rs->search({ name => 'fred', 'cd.artist' => 'luke' }, { join => ['cd'] })It is also possible to use a JSON string for expandeded parameters:
?search.datetime={"-between":["2010-01-06 19:28:00","2010-01-07 19:28:00"]}Note that if pagination is needed, this can be achieved using a combination of the "count" and "page" parameters. For example:
?page=2&count=20Would result in this search:
$rs->search({}, { page => 2, rows => 20 })list_munge_parameters
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. To store the munged parameters call $c->req->_set_search_parameters($newparams) and $c->req->_set_search_attributes($newattrs).
list_perform_search
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.
list_format_output
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 DBIx::Class::ResultClass::HashRefInflator. Each row in the resultset is then iterated and passed to "row_format_output" with the result of that call added to the output.
row_format_output
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.
item
item will return a single object called by identifier in the uri. It will be inflated via each_object_inflate.
update_or_create
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 "create_requires" and "create_allows" (or "update_allows") parameters of the controller config. The objects are then committed within a transaction via "transact_objects" using a closure around "save_objects".
transact_objects
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.
validate_objects
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.
validate_object
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.
delete
delete operates on the stored objects in the request. It first transacts the objects, deleting them in the database using "transact_objects" and a closure around "delete_objects", and then clears the request store of objects.
save_objects
This method is used by update_or_create to perform the actual database manipulations. It iterates each object calling "save_object".
save_object
save_object first checks to see if the object is already in storage. If so, it calls "update_object_from_params" otherwise "insert_object_from_params".
update_object_from_params
update_object_from_params iterates through the params to see if any of them are pertinent to relations. If so it calls "update_object_relation" with the object, and the relation parameters. Then it calls ->update on the object.
update_object_relation
update_object_relation finds the relation to the object, then calls ->update with the specified parameters.
insert_object_from_params
Sets the columns of the object, then calls ->insert.
delete_objects
Iterates through each object calling "delete_object".
delete_object
Performs the actual ->delete on the object.
end
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
each_object_inflate
each_object_inflate executes during "end" and allows hooking into the process of inflating the objects to return in the response. Receives, the context, and the object as arguments.
This only executes if "return_object" if set and if there are any objects to actually return.
serialize
multiple actions forward to serialize which uses Catalyst::Action::Serialize.
push_error
Stores an error message into the stash to be later retrieved by "end". Accepts a Dict[message => Str] parameter that defines the error message.
get_errors
Returns all of the errors stored in the stash.
has_errors
Returns true if errors are stored in the stash.
PRIVATE_METHODS
begin
:Privatebegin is provided in the base class to setup the Catalyst request object by applying the DBIC::API::Request role.
EXTENDING
By default the create, delete and update actions will not return anything apart from the success parameter set in "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.
For example if you wanted create to return the JSON for the newly created object you might have something like:
package MyApp::ControllerBase::DBIC::API::RPC;
...
use Moose;
BEGIN { extends 'Catalyst::Controller::DBIC::API::RPC' };
...
sub create :Chained('setup') :Args(0) :PathPart('create') {
my ($self, $c) = @_;
# $c->req->all_objects will contain all of the created
$self->next::method($c);
if ($c->req->has_objects) {
# $c->stash->{$self->stash_key} will be serialized in the end action
$c->stash->{$self->stash_key}->{$self->data_root} = [ map { { $_->get_inflated_columns } } ($c->req->all_objects) ] ;
}
}
package MyApp::Controller::API::RPC::Track;
...
use Moose;
BEGIN { extends 'MyApp::ControllerBase::DBIC::API::RPC' };
...It should be noted that the return_object attribute will produce the above result for you, free of charge.
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.
If more extensive customization is required, it is recommened to peer into the roles that comprise the system and make use
NOTES
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.
To this end, internally, this module now understands JSON boolean values (as represented by the JSON::MaybeXS 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.
Validation for various *_allows or *_exposes is now accomplished via Data::DPath::Validator with a lightly simplified, via a subclass of 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 Data::DPath::Validator and more specifically Catalyst::Controller::DBIC::API::Validator.
Since 2.001: Transactions are used. The stash is put aside in favor of roles applied to the request object with additional accessors. Error handling is now much more consistent with most errors immediately detaching. The internals are much easier to read and understand with lots more documentation.
Since 2.006: The SQL::Abstract -and, -not and -or operators are supported.
AUTHORS
Nicholas Perez <nperez@cpan.org>
Luke Saunders <luke.saunders@gmail.com>
Alexander Hartmaier <abraxxa@cpan.org>
Florian Ragwitz <rafl@debian.org>
Oleg Kostyuk <cub.uanic@gmail.com>
Samuel Kaufman <sam@socialflow.com>
COPYRIGHT AND LICENSE
This software is copyright (c) 2018 by Luke Saunders, Nicholas Perez, Alexander Hartmaier, et al.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.