From: Alexander Hartmaier Date: Mon, 13 Jan 2014 18:45:19 +0000 (+0100) Subject: documentation improvements X-Git-Tag: 2.005001~2 X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=catagits%2FCatalyst-Controller-DBIC-API.git;a=commitdiff_plain;h=c0c8e1c607a024ac8425f6f7d889d35cd63bcebc documentation improvements I've decided to not include the Moose method attributes in the pod for better readability and links e.g. on MetaCPAN. --- diff --git a/Changes b/Changes index 0cebe70..29d2b00 100644 --- a/Changes +++ b/Changes @@ -7,6 +7,7 @@ Revision history for Catalyst-Controller-DBIC-API: {{ $dist->version }} - Use Catalyst's http method matching for REST instead of ActionRole, whose feature went into core in 5.90013, and MatchRequestMethod, whose feature went into 5.90020 + - Documentation improvements 2.004004 2012-11-21T12:20:41Z Europe/Vienna - Fixed test failures in t/[rest,rpc]/item.t on newer HTTP::Message diff --git a/lib/Catalyst/Controller/DBIC/API.pm b/lib/Catalyst/Controller/DBIC/API.pm index bbfb536..7cfb6e6 100644 --- a/lib/Catalyst/Controller/DBIC/API.pm +++ b/lib/Catalyst/Controller/DBIC/API.pm @@ -79,7 +79,8 @@ __PACKAGE__->config(); :Private -begin is provided in the base class to setup the Catalyst Request object, by applying the DBIC::API::Request role. +begin is provided in the base class to setup the Catalyst request object by +applying the DBIC::API::Request role. =cut @@ -126,7 +127,11 @@ sub setup : Chained('specify.in.subclass.config') : CaptureArgs(0) : :Chained('setup') :CaptureArgs(0) :PathPart('') :ActionClass('Deserialize') -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: +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 @@ -135,7 +140,11 @@ deserialize absorbs the request data and transforms it into useful bits by using grouped_by_arg prefetch_arg -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. +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. =cut @@ -217,7 +226,8 @@ sub generate_rs { =method_protected inflate_request -inflate_request is called at the end of deserialize to populate key portions of the request with the useful bits +inflate_request is called at the end of deserialize to populate key portions of +the request with the useful bits. =cut @@ -246,7 +256,12 @@ sub inflate_request { :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 of objects. Please see L for more details on the stored objects. +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 L for more details on the +stored objects. =cut @@ -275,7 +290,16 @@ sub object_with_id : Chained('deserialize') : CaptureArgs(1) : PathPart('') { :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 L for more details on the stored objects. +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 for more details on the +stored objects. =cut @@ -330,7 +354,9 @@ sub objects_no_id : Chained('deserialize') : CaptureArgs(0) : PathPart('') { =method_protected 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. +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. =cut @@ -345,13 +371,44 @@ sub object_lookup { =method_protected list -list's steps are broken up into three distinct methods: L, L, and L. +list's steps are broken up into three distinct methods: + +=over + +=item L + +=item L -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. +=item L. -If the L config param is defined then the hashes will contain only those columns, otherwise all columns in the object will be returned. L of course supports the function/procedure calling semantics that L. In order to have proper column names in the result, provide arguments in L (which also follows L semantics. Similarly L, L, L and L 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. +=back -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 syntax. In the second case the request parameters are expanded into a structure and then used as the search condition. +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 L config param is defined then the hashes will contain only +those columns, otherwise all columns in the object will be returned. +L of course supports the function/procedure calling semantics that +L supports. + +In order to have proper column names in the result, provide arguments in L +(which also follows L semantics. +Similarly L, L, L and L 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 L 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: @@ -359,7 +416,8 @@ For example, these request parameters: OR ?search={"name":"fred","cd": {"artist":"luke"}} -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): +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'] }) @@ -367,7 +425,8 @@ 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 L and L parameters. For example: +Note that if pagination is needed, this can be achieved using a combination of +the L and L parameters. For example: ?page=2&count=20 @@ -390,8 +449,14 @@ sub list { =method_protected 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_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). =cut @@ -399,7 +464,9 @@ sub list_munge_parameters { } # noop by default =method_protected 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_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. =cut @@ -432,7 +499,11 @@ sub list_perform_search { =method_protected 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 L. Each row in the resultset is then iterated and passed to L with the result of that call added to the 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 +L. Each row in the resultset is then +iterated and passed to L with the result of that call added +to the output. =cut @@ -469,7 +540,9 @@ sub list_format_output { =method_protected 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. +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. =cut @@ -482,7 +555,8 @@ sub row_format_output { =method_protected item -item will return a single object called by identifier in the uri. It will be inflated via each_object_inflate. +item will return a single object called by identifier in the uri. It will be +inflated via each_object_inflate. =cut @@ -503,7 +577,12 @@ sub item { =method_protected 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 L and L (or L) parameters of the controller config. The objects are then committed within a transaction via L using a closure around L. +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 and L (or +L) parameters of the controller config. The objects are then +committed within a transaction via L using a closure around +L. =cut @@ -524,7 +603,10 @@ sub update_or_create { =method_protected 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. +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. =cut @@ -545,7 +627,9 @@ sub transact_objects { =method_protected 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. +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. =cut @@ -568,7 +652,11 @@ sub validate_objects { =method_protected 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. +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. =cut @@ -655,7 +743,9 @@ sub validate_object { =method_protected delete -delete operates on the stored objects in the request. It first transacts the objects, deleting them in the database using L and a closure around L, and then clears the request store of objects. +delete operates on the stored objects in the request. It first transacts the +objects, deleting them in the database using L and a closure +around L, and then clears the request store of objects. =cut @@ -677,7 +767,8 @@ sub delete { =method_protected save_objects -This method is used by update_or_create to perform the actual database manipulations. It iterates each object calling L. +This method is used by update_or_create to perform the actual database +manipulations. It iterates each object calling L. =cut @@ -691,7 +782,8 @@ sub save_objects { =method_protected save_object -save_object first checks to see if the object is already in storage. If so, it calls L otherwise it calls L +save_object first checks to see if the object is already in storage. If so, it +calls L otherwise L. =cut @@ -711,7 +803,9 @@ sub save_object { =method_protected 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 L with the object, and the relation parameters. Then it calls ->update on the object. +update_object_from_params iterates through the params to see if any of them are +pertinent to relations. If so it calls L with the +object, and the relation parameters. Then it calls ->update on the object. =cut @@ -743,7 +837,8 @@ sub update_object_from_params { =method_protected update_object_relation -update_object_relation finds the relation to the object, then calls ->update with the specified parameters +update_object_relation finds the relation to the object, then calls ->update +with the specified parameters. =cut @@ -781,7 +876,7 @@ sub update_object_relation { =method_protected insert_object_from_params -insert_object_from_params sets the columns for the object, then calls ->insert +Sets the columns of the object, then calls ->insert. =cut @@ -818,7 +913,7 @@ sub insert_object_from_params { =method_protected delete_objects -delete_objects iterates through each object calling L +Iterates through each object calling L. =cut @@ -830,7 +925,7 @@ sub delete_objects { =method_protected delete_object -Performs the actual ->delete on the object +Performs the actual ->delete on the object. =cut @@ -844,7 +939,11 @@ sub delete_object { =method_protected 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 +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 =cut @@ -889,9 +988,12 @@ sub end : Private { =method_protected each_object_inflate -each_object_inflate executes during L and allows hooking into the process of inflating the objects to return in the response. Receives, the context, and the object as arguments. +each_object_inflate executes during L 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 L if set and if there are any objects to actually return. +This only executes if L if set and if there are any objects to +actually return. =cut @@ -914,7 +1016,8 @@ sub serialize : ActionClass('Serialize') { } =method_protected push_error -push_error stores an error message into the stash to be later retrieved by L. Accepts a Dict[message => Str] parameter that defines the error message. +Stores an error message into the stash to be later retrieved by L. +Accepts a Dict[message => Str] parameter that defines the error message. =cut @@ -935,7 +1038,7 @@ sub push_error { =method_protected get_errors -get_errors returns all of the errors stored in the stash +Returns all of the errors stored in the stash. =cut @@ -948,7 +1051,7 @@ sub get_errors { =method_protected has_errors -returns returns true if errors are stored in the stash +Returns true if errors are stored in the stash. =cut @@ -961,21 +1064,38 @@ sub has_errors { =head1 DESCRIPTION -Easily provide common API endpoints based on your L schema classes. Module provides both RPC and REST interfaces to base functionality. Uses L and L to serialise response and/or deserialise request. +Easily provide common API endpoints based on your L schema classes. +Module provides both RPC and REST interfaces to base functionality. +Uses L and L to +serialize response and/or deserialise request. =head1 OVERVIEW -This document describes base functionlity such as list, create, delete, update and the setting of config attributes. L and L describe details of provided endpoints to those base methods. +This document describes base functionlity such as list, create, delete, update +and the setting of config attributes. L +and L 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 L. Similarly if you wanted to provide an RPC style interface then subclass L. You then configure these individually as specified in L. +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. +Similarly if you wanted to provide an RPC style interface then subclass +L. You then configure these individually +as specified in L. -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. +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. =head2 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 L. +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. -The class, create_requires, create_allows and update_requires parameters can also be set in the stash like so: +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) = @_; @@ -992,19 +1112,27 @@ The class, create_requires, create_allows and update_requires parameters can als $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. +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 L for more details. +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 for more details. -Below are explanations for various configuration parameters. Please see L for more details. +Below are explanations for various configuration parameters. Please see +L for more details. =head3 class -Whatever you would pass to $c->model to get a resultset for this class. MyAppDB::Track for example. +Whatever you would pass to $c->model to get a resultset for this class. +MyAppDB::Track for example. =head3 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. +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. =head3 stash_key @@ -1012,43 +1140,60 @@ Controls where in stash request_data should be stored, and defaults to 'response =head3 data_root -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. +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. =head3 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's true() and false() will be used instead. Note, this does not effect other internal processing of boolean values. +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. =head3 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. +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. =head3 create_requires -Arrayref listing columns required to be passed to create in order for the request to be valid. +Arrayref listing columns required to be passed to create in order for the +request to be valid. =head3 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. +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. =head3 update_allows -Arrayref listing columns that update will allow. Columns passed to update that are not listed here will be ignored. +Arrayref listing columns that update will allow. Columns passed to update that +are not listed here will be ignored. =head3 select -Arguments to pass to L when performing search for L. +Arguments to pass to L when performing search for +L. =head3 as -Complements arguments passed to L when performing a search. This allows you to specify column names in the result for RDBMS functions, etc. +Complements arguments passed to L when performing +a search. This allows you to specify column names in the result for RDBMS +functions, etc. =head3 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. +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. =head3 prefetch -Arguments to pass to L when performing search for L. +Arguments to pass to L when performing search +for L. =head3 prefetch_allows @@ -1059,19 +1204,23 @@ and unwanted disclosure of data. =head3 grouped_by -Arguments to pass to L when performing search for L. +Arguments to pass to L when performing search +for L. =head3 ordered_by -Arguments to pass to L when performing search for L. +Arguments to pass to L when performing search +for L. =head3 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 +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: +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; @@ -1101,17 +1250,24 @@ and then in your custom resultset: =head3 count -Arguments to pass to L when performing search for L. +Arguments to pass to L when performing search for +L. =head3 page -Arguments to pass to L when performing search for L. +Arguments to pass to L when performing search for +L. =head1 EXTENDING -By default the create, delete and update actions will not return anything apart from the success parameter set in L, 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. +By default the create, delete and update actions will not return anything apart +from the success parameter set in L, 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: +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; ... @@ -1136,22 +1292,41 @@ For example if you wanted create to return the JSON for the newly created object 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. +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. +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 +If more extensive customization is required, it is recommened to peer into the +roles that comprise the system and make use =head1 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. +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 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. -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. +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. -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 and more specifically L. +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 and more specifically +L. Since 2.00100: -Transactions are used. The stash is put aside in favor of roles applied to the request object with additional accessors. +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. diff --git a/lib/Catalyst/Controller/DBIC/API/JoinBuilder.pm b/lib/Catalyst/Controller/DBIC/API/JoinBuilder.pm index e2c6f30..fdad42a 100644 --- a/lib/Catalyst/Controller/DBIC/API/JoinBuilder.pm +++ b/lib/Catalyst/Controller/DBIC/API/JoinBuilder.pm @@ -6,9 +6,9 @@ use MooseX::Types::Moose(':all'); use Catalyst::Controller::DBIC::API::Types(':all'); use namespace::autoclean; -=attribute_public parent is: ro, isa: 'Catalyst::Controller::DBIC::API::JoinBuilder' +=attribute_public parent -parent stores the direct ascendant in the datastructure that represents the join +Stores the direct ascendant in the datastructure that represents the join. =cut @@ -20,9 +20,9 @@ has parent => ( trigger => sub { my ( $self, $new ) = @_; $new->add_child($self); }, ); -=attribute_public children is: ro, isa: ArrayRef['Catalyst::Controller::DBIC::API::JoinBuilder'], traits => ['Array'] +=attribute_public children -children stores the immediate descendants in the datastructure that represents the join. +Stores the immediate descendants in the datastructure that represents the join. Handles the following methods: @@ -44,9 +44,9 @@ has children => ( } ); -=attribute_public joins is: ro, isa: HashRef, lazy_build: true +=attribute_public joins -joins holds the cached generated join datastructure. +Holds the cached, generated join datastructure. =cut @@ -56,9 +56,9 @@ has joins => ( lazy_build => 1, ); -=attribute_public name is: ro, isa: Str, required: 1 +=attribute_public name -Sets the key for this level in the generated hash +Sets the key for this level in the generated hash. =cut @@ -70,7 +70,8 @@ has name => ( =method_private _build_joins -_build_joins finds the top parent in the structure and then recursively iterates the children building out the join datastructure +Finds the top parent in the structure and then recursively iterates the children +building out the join datastructure. =cut @@ -99,7 +100,10 @@ sub _build_joins { =head1 DESCRIPTION -JoinBuilder is used to keep track of joins automgically for complex searches. It accomplishes this by building a simple tree of parents and children and then recursively drilling into the tree to produce a useable join attribute for ->search. +JoinBuilder is used to keep track of joins automagically for complex searches. +It accomplishes this by building a simple tree of parents and children and then +recursively drilling into the tree to produce a useable join attribute for +search. =cut diff --git a/lib/Catalyst/Controller/DBIC/API/REST.pm b/lib/Catalyst/Controller/DBIC/API/REST.pm index 4e6c8bc..4b49562 100644 --- a/lib/Catalyst/Controller/DBIC/API/REST.pm +++ b/lib/Catalyst/Controller/DBIC/API/REST.pm @@ -15,14 +15,17 @@ __PACKAGE__->config( =head1 DESCRIPTION -Provides a REST style API interface to the functionality described in L. +Provides a REST style API interface to the functionality described in +L. By default provides the following endpoints: $base (operates on lists of objects and accepts GET, PUT, POST and DELETE) $base/[identifier] (operates on a single object and accepts GET, PUT, POST and DELETE) -Where $base is the URI described by L, the chain root of the controller, and the request type will determine the L method to forward. +Where $base is the URI described by L, the chain root of the controller +and the request type will determine the L +method to forward. =method_protected setup @@ -30,7 +33,13 @@ Chained: override PathPart: override CaptureArgs: 0 -As described in L, this action is the chain root of the controller but has no pathpart or chain parent defined by default, so these must be defined in order for the controller to function. The neatest way is normally to define these using the controller's config. +As described in L, this action is the +chain root of the controller but has no pathpart or chain parent defined by +default. + +These must be defined in order for the controller to function. + +The neatest way is normally to define these using the controller's config. __PACKAGE__->config ( action => { setup => { PathPart => 'track', Chained => '/api/rest/rest_base' } }, diff --git a/lib/Catalyst/Controller/DBIC/API/RPC.pm b/lib/Catalyst/Controller/DBIC/API/RPC.pm index 343c646..adfb7ea 100644 --- a/lib/Catalyst/Controller/DBIC/API/RPC.pm +++ b/lib/Catalyst/Controller/DBIC/API/RPC.pm @@ -17,7 +17,8 @@ __PACKAGE__->config( =head1 DESCRIPTION -Provides an RPC API interface to the functionality described in L. +Provides an RPC API interface to the functionality described in +L. By default provides the following endpoints: @@ -35,7 +36,13 @@ Chained: override PathPart: override CaptureArgs: 0 -As described in L, this action is the chain root of the controller but has no pathpart or chain parent defined by default, so these must be defined in order for the controller to function. The neatest way is normally to define these using the controller's config. +As described in L, this action is the +chain root of the controller but has no pathpart or chain parent defined by +default. + +These must be defined in order for the controller to function. + +The neatest way is normally to define these using the controller's config. __PACKAGE__->config ( action => { setup => { PathPart => 'track', Chained => '/api/rpc/rpc_base' } }, @@ -50,7 +57,8 @@ Chained: L PathPart: create CaptureArgs: 0 -Provides an endpoint to the functionality described in L. +Provides an endpoint to the functionality described in +L. =cut @@ -65,7 +73,8 @@ Chained: L PathPart: list CaptureArgs: 0 -Provides an endpoint to the functionality described in L. +Provides an endpoint to the functionality described in +L. =cut @@ -80,7 +89,8 @@ Chained: L PathPart: '' Args: 0 -Provides an endpoint to the functionality described in L. +Provides an endpoint to the functionality described in +L. =cut @@ -95,7 +105,8 @@ Chained: L PathPart: update Args: 0 -Provides an endpoint to the functionality described in L. +Provides an endpoint to the functionality described in +L. =cut @@ -110,7 +121,8 @@ Chained: L PathPart: delete Args: 0 -Provides an endpoint to the functionality described in L. +Provides an endpoint to the functionality described in +L. =cut @@ -125,7 +137,8 @@ Chained: L PathPart: update Args: 0 -Provides an endpoint to the functionality described in L for multiple objects. +Provides an endpoint to the functionality described in +L for multiple objects. =cut @@ -140,7 +153,8 @@ Chained: L PathPart: delete Args: 0 -Provides an endpoint to the functionality described in L for multiple objects. +Provides an endpoint to the functionality described in +L for multiple objects. =cut diff --git a/lib/Catalyst/Controller/DBIC/API/Request.pm b/lib/Catalyst/Controller/DBIC/API/Request.pm index ab44dac..3470e92 100644 --- a/lib/Catalyst/Controller/DBIC/API/Request.pm +++ b/lib/Catalyst/Controller/DBIC/API/Request.pm @@ -10,9 +10,11 @@ use namespace::autoclean; sub _application { } sub _controller { } -=attribute_private _application is: ro, isa: Object|ClassName, handles: Catalyst::Controller::DBIC::API::StoredResultSource +=attribute_private _application -This attribute helps bridge between the request guts and the application guts; allows request argument validation against the schema. This is set during L +This attribute helps bridge between the request guts and the application guts; +allows request argument validation against the schema. This is set during +L. =cut @@ -43,7 +45,9 @@ with 'Catalyst::Controller::DBIC::API::StoredResultSource', =head1 DESCRIPTION -Please see L and L for the details of this class, as both of those roles are consumed in this role. +Please see L and +L for the details of this +class, as both of those roles are consumed in this role. =cut diff --git a/lib/Catalyst/Controller/DBIC/API/Request/Context.pm b/lib/Catalyst/Controller/DBIC/API/Request/Context.pm index 0ca085b..2bc0771 100644 --- a/lib/Catalyst/Controller/DBIC/API/Request/Context.pm +++ b/lib/Catalyst/Controller/DBIC/API/Request/Context.pm @@ -7,10 +7,7 @@ use MooseX::Types::Structured('Tuple'); use Catalyst::Controller::DBIC::API::Types(':all'); use namespace::autoclean; -=attribute_public objects is: - ro - isa ArrayRef[Tuple[Object,Maybe[HashRef]]] - traits: ['Array'] +=attribute_public objects This attribute stores the objects found/created at the object action. It handles the following methods: @@ -38,9 +35,7 @@ has objects => ( }, ); -=attribute_public current_result_set is: - ro - isa: L +=attribute_public current_result_set Stores the current ResultSet derived from the initial L. diff --git a/lib/Catalyst/Controller/DBIC/API/RequestArguments.pm b/lib/Catalyst/Controller/DBIC/API/RequestArguments.pm index 65588db..eff9884 100644 --- a/lib/Catalyst/Controller/DBIC/API/RequestArguments.pm +++ b/lib/Catalyst/Controller/DBIC/API/RequestArguments.pm @@ -13,19 +13,22 @@ use Catalyst::Controller::DBIC::API::JoinBuilder; =attribute_private search_validator -A Catalyst::Controller::DBIC::API::Validator instance used solely to validate search parameters +A Catalyst::Controller::DBIC::API::Validator instance used solely to validate +search parameters. =cut =attribute_private select_validator -A Catalyst::Controller::DBIC::API::Validator instance used solely to validate select parameters +A Catalyst::Controller::DBIC::API::Validator instance used solely to validate +select parameters. =cut =attribute_private prefetch_validator -A Catalyst::Controller::DBIC::API::Validator instance used solely to validate prefetch parameters +A Catalyst::Controller::DBIC::API::Validator instance used solely to validate +prefetch parameters. =cut @@ -53,9 +56,9 @@ role { requires qw( _controller check_has_relation check_column_relation ); } -=attribute_public count is: ro, isa: Int +=attribute_public count -count is the number of rows to be returned during paging +The number of rows to be returned during paging. =cut @@ -66,9 +69,9 @@ count is the number of rows to be returned during paging predicate => 'has_count', ); -=attribute_public page is: ro, isa: Int +=attribute_public page -page is what page to return while paging +What page to return while paging. =cut @@ -79,9 +82,9 @@ page is what page to return while paging predicate => 'has_page', ); -=attribute_public offset is ro, isa: Int +=attribute_public offset -offset specifies where to start the paged result (think SQL LIMIT) +Specifies where to start the paged result (think SQL LIMIT). =cut @@ -92,9 +95,9 @@ offset specifies where to start the paged result (think SQL LIMIT) predicate => 'has_offset', ); -=attribute_public ordered_by is: ro, isa: L +=attribute_public ordered_by -ordered_by is passed to ->search to determine sorting +Is passed to ->search to determine sorting. =cut @@ -107,9 +110,9 @@ ordered_by is passed to ->search to determine sorting default => sub { $p->static ? [] : undef }, ); -=attribute_public groupd_by is: ro, isa: L +=attribute_public groupd_by -grouped_by is passed to ->search to determine aggregate results +Is passed to ->search to determine aggregate results. =cut @@ -122,9 +125,9 @@ grouped_by is passed to ->search to determine aggregate results default => sub { $p->static ? [] : undef }, ); -=attribute_public prefetch is: ro, isa: L +=attribute_public prefetch -prefetch is passed to ->search to optimize the number of database fetches for joins +Is passed to ->search to optimize the number of database fetches for joins. =cut @@ -153,11 +156,15 @@ prefetch is passed to ->search to optimize the number of database fetches for jo }, ); -=attribute_public search_exposes is: ro, isa: ArrayRef[Str|HashRef] +=attribute_public search_exposes -search_exposes limits what can actually be searched. If a certain column isn't indexed or perhaps a BLOB, you can explicitly say which columns can be search and exclude that one. +Limits what can actually be searched. If a certain column isn't indexed or +perhaps a BLOB, you can explicitly say which columns can be search to exclude +that one. -Like the synopsis in DBIC::API shows, you can declare a "template" of what is allowed (by using an '*'). Each element passed in, will be converted into a Data::DPath and added to the validator. +Like the synopsis in DBIC::API shows, you can declare a "template" of what is +allowed (by using '*'). Each element passed in, will be converted into a +Data::DPath and added to the validator. =cut @@ -173,9 +180,10 @@ Like the synopsis in DBIC::API shows, you can declare a "template" of what is al }, ); -=attribute_public search is: ro, isa: L +=attribute_public search -search contains the raw search parameters. Upon setting, a trigger will fire to format them, set search_parameters, and set search_attributes. +Contains the raw search parameters. Upon setting, a trigger will fire to format +them, set search_parameters and search_attributes. Please see L for details on how the format works. @@ -217,9 +225,9 @@ Please see L for details on how the format work }, ); -=attribute_public search_parameters is:ro, isa: L +=attribute_public search_parameters -search_parameters stores the formatted search parameters that will be passed to ->search +Stores the formatted search parameters that will be passed to ->search. =cut @@ -232,9 +240,9 @@ search_parameters stores the formatted search parameters that will be passed to default => sub { [ {} ] }, ); -=attribute_public search_attributes is:ro, isa: HashRef +=attribute_public search_attributes -search_attributes stores the formatted search attributes that will be passed to ->search +Stores the formatted search attributes that will be passed to ->search. =cut @@ -246,9 +254,9 @@ search_attributes stores the formatted search attributes that will be passed to lazy_build => 1, ); -=attribute_public search_total_entries is: ro, isa: Int +=attribute_public search_total_entries -search_total_entries stores the total number of entries in a paged search result +Stores the total number of entries in a paged search result. =cut @@ -259,11 +267,14 @@ search_total_entries stores the total number of entries in a paged search result predicate => 'has_search_total_entries', ); -=attribute_public select_exposes is: ro, isa: ArrayRef[Str|HashRef] +=attribute_public select_exposes -select_exposes limits what can actually be selected. Use this to whitelist database functions (such as COUNT). +Limits what can actually be selected. Use this to whitelist database functions +(such as COUNT). -Like the synopsis in DBIC::API shows, you can declare a "template" of what is allowed (by using an '*'). Each element passed in, will be converted into a Data::DPath and added to the validator. +Like the synopsis in DBIC::API shows, you can declare a "template" of what is +allowed (by using '*'). Each element passed in, will be converted into a +Data::DPath and added to the validator. =cut @@ -279,9 +290,10 @@ Like the synopsis in DBIC::API shows, you can declare a "template" of what is al }, ); -=attribute_public select is: ro, isa: L +=attribute_public select -select is the search attribute that allows you to both limit what is returned in the result set, and also make use of database functions like COUNT. +Is the search attribute that allows you to both limit what is returned in the +result set and also make use of database functions like COUNT. Please see L for more details. @@ -308,9 +320,11 @@ Please see L for more details. }, ); -=attribute_public as is: ro, isa: L +=attribute_public as -as is the search attribute compliment to L that allows you to label columns for object inflaction and actually reference database functions like COUNT. +Is the search attribute compliment to L that allows you to label +columns for object inflaction and actually reference database functions like +COUNT. Please see L for more details. @@ -334,13 +348,13 @@ Please see L for more details. } ); -=attribute_public joins is: ro, isa L +=attribute_public joins -joins holds the top level JoinBuilder object used to keep track of joins automagically while formatting complex search parameters. +Holds the top level JoinBuilder object used to keep track of joins automagically +while formatting complex search parameters. -Provides a single handle which returns the 'join' attribute for search_attributes: - - build_joins => 'joins' +Provides the method 'build_joins' which returns the 'join' attribute for +search_attributes. =cut @@ -351,9 +365,9 @@ Provides a single handle which returns the 'join' attribute for search_attribute handles => { build_joins => 'joins', } ); -=attribute_public request_data is: ro, isa: HashRef +=attribute_public request_data -request_data holds the raw (but deserialized) data for ths request +Holds the raw (but deserialized) data for this request. =cut @@ -394,7 +408,8 @@ request_data holds the raw (but deserialized) data for ths request =method_protected format_search_parameters -format_search_parameters iterates through the provided params ArrayRef, calling generate_column_parameters on each one +Iterates through the provided arrayref calling generate_column_parameters on +each one. =cut @@ -418,7 +433,8 @@ format_search_parameters iterates through the provided params ArrayRef, calling =method_protected generate_column_parameters -generate_column_parameters recursively generates properly aliased parameters for search, building a new JoinBuilder each layer of recursion +Recursively generates properly aliased parameters for search building a new +JoinBuilder each layer of recursion. =cut @@ -480,7 +496,12 @@ generate_column_parameters recursively generates properly aliased parameters for =method_protected generate_parameters_attributes -generate_parameters_attributes takes the raw search arguments and formats the parameters by calling format_search_parameters. Then builds the related attributes, preferring request-provided arguments for things like grouped_by over statically configured options. Finally tacking on the appropriate joins. Returns both formatted search parameters and the search attributes. +Takes the raw search arguments and formats them by calling +format_search_parameters. Then builds the related attributes, preferring +request-provided arguments for things like grouped_by over statically configured +options. Finally tacking on the appropriate joins. + +Returns a list of both formatted search parameters and attributes. =cut @@ -493,7 +514,7 @@ generate_parameters_attributes takes the raw search arguments and formats the pa =method_protected _build_search_attributes -This builder method generates the search attributes +This builder method generates the search attributes. =cut diff --git a/lib/Catalyst/Controller/DBIC/API/StaticArguments.pm b/lib/Catalyst/Controller/DBIC/API/StaticArguments.pm index 1a20acf..0ec6c0d 100644 --- a/lib/Catalyst/Controller/DBIC/API/StaticArguments.pm +++ b/lib/Catalyst/Controller/DBIC/API/StaticArguments.pm @@ -9,7 +9,8 @@ requires 'check_column_relation'; =attribute_public create_requires create_allows update_requires update_allows -These attributes control requirements and limits to columns when creating or updating objects. +These attributes control requirements and limits to columns when creating or +updating objects. Each provides a number of handles: @@ -50,11 +51,16 @@ foreach my $var ( sub { $_[0]->check_column_relation( $_[2], 1 ) }; } -=attribute_public prefetch_allows is: ro, isa: ArrayRef[ArrayRef|Str|HashRef] +=attribute_public prefetch_allows -prefetch_allows limits what relations may be prefetched when executing searches with joins. 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. +prefetch_allows limits what relations may be prefetched when executing searches +with joins. 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. -Like the synopsis in DBIC::API shows, you can declare a "template" of what is allowed (by using an '*'). Each element passed in, will be converted into a Data::DPath and added to the validator. +Like the synopsis in DBIC::API shows, you can declare a "template" of what is +allowed (by using an '*'). Each element passed in, will be converted into a +Data::DPath and added to the validator. prefetch_allows => [ 'cds', { cds => tracks }, { cds => producers } ] # to be explicit prefetch_allows => [ 'cds', { cds => '*' } ] # wildcard means the same thing @@ -108,125 +114,138 @@ sub _build_prefetch_validator { return $validator; } -=attribute_public count_arg is: ro, isa: Str, default: 'list_count' +=attribute_public count_arg -count_arg controls how to reference 'count' in the the request_data +Controls how to reference 'count' in the the request_data, defaults to +'list_count'. =cut has 'count_arg' => ( is => 'ro', isa => Str, default => 'list_count' ); -=attribute_public page_arg is: ro, isa: Str, default: 'list_page' +=attribute_public page_arg -page_arg controls how to reference 'page' in the the request_data +Controls how to reference 'page' in the the request_data, defaults to +'list_page'. =cut has 'page_arg' => ( is => 'ro', isa => Str, default => 'list_page' ); -=attribute_public offset_arg is: ro, isa: Str, default: 'list_offset' +=attribute_public offset_arg -offset_arg controls how to reference 'offset' in the the request_data +Controls how to reference 'offset' in the the request_data, defaults to +'list_offset'. =cut has 'offset_arg' => ( is => 'ro', isa => Str, default => 'list_offset' ); -=attribute_public select_arg is: ro, isa: Str, default: 'list_returns' +=attribute_public select_arg -select_arg controls how to reference 'select' in the the request_data +Controls how to reference 'select' in the the request_data, defaults to +'list_returns'. =cut has 'select_arg' => ( is => 'ro', isa => Str, default => 'list_returns' ); -=attribute_public as_arg is: ro, isa: Str, default: 'as' +=attribute_public as_arg -as_arg controls how to reference 'as' in the the request_data +Controls how to reference 'as' in the the request_data, defaults to 'as'. =cut has 'as_arg' => ( is => 'ro', isa => Str, default => 'as' ); -=attribute_public search_arg is: ro, isa: Str, default: 'search' +=attribute_public search_arg -search_arg controls how to reference 'search' in the the request_data +Controls how to reference 'search' in the the request_data, defaults to +'search'. =cut has 'search_arg' => ( is => 'ro', isa => Str, default => 'search' ); -=attribute_public grouped_by_arg is: ro, isa: Str, default: 'list_grouped_by' +=attribute_public grouped_by_arg -grouped_by_arg controls how to reference 'grouped_by' in the the request_data +Controls how to reference 'grouped_by' in the the request_data, defaults to +'list_grouped_by'. =cut has 'grouped_by_arg' => ( is => 'ro', isa => Str, default => 'list_grouped_by' ); -=attribute_public ordered_by_arg is: ro, isa: Str, default: 'list_ordered_by' +=attribute_public ordered_by_arg -ordered_by_arg controls how to reference 'ordered_by' in the the request_data +Controls how to reference 'ordered_by' in the the request_data, defaults to +'list_ordered_by'. =cut has 'ordered_by_arg' => ( is => 'ro', isa => Str, default => 'list_ordered_by' ); -=attribute_public prefetch_arg is: ro, isa: Str, default: 'list_prefetch' +=attribute_public prefetch_arg -prefetch_arg controls how to reference 'prefetch' in the the request_data +Controls how to reference 'prefetch' in the the request_data, defaults to +'list_prefetch'. =cut has 'prefetch_arg' => ( is => 'ro', isa => Str, default => 'list_prefetch' ); -=attribute_public stash_key is: ro, isa: Str, default: 'response' +=attribute_public stash_key -stash_key controls where in stash request_data should be stored +Controls where in the stash the request_data should be stored, defaults to +'response'. =cut has 'stash_key' => ( is => 'ro', isa => Str, default => 'response' ); -=attribute_public data_root is: ro, isa: Str, default: 'list' +=attribute_public data_root -data_root controls how to reference where the data is in the the request_data +Controls how to reference where the data is in the the request_data, defaults to +'list'. =cut has 'data_root' => ( is => 'ro', isa => Str, default => 'list' ); -=attribute_public item_root is: ro, isa: Str, default: 'data' +=attribute_public item_root -item_root controls how to reference where the data for single object -requests is in the the request_data +Controls how to reference where the data for single object requests is in the +the request_data, defaults to 'data'. =cut has 'item_root' => ( is => 'ro', isa => Str, default => 'data' ); -=attribute_public total_entries_arg is: ro, isa: Str, default: 'totalcount' +=attribute_public total_entries_arg -total_entries_arg controls how to reference 'total_entries' in the the request_data +Controls how to reference 'total_entries' in the the request_data, defaults to +'totalcount'. =cut has 'total_entries_arg' => ( is => 'ro', isa => Str, default => 'totalcount' ); -=attribute_public use_json_boolean is: ro, isa: Bool, default: 0 +=attribute_public use_json_boolean -use_json_boolean controls whether JSON boolean types are used in the success parameter of the response or if raw strings are used +Controls whether JSON boolean types are used in the success parameter of the +response or if raw strings are used, defaults to false. =cut has 'use_json_boolean' => ( is => 'ro', isa => Bool, default => 0 ); -=attribute_public return_object is: ro, isa: Bool, default: 0 +=attribute_public return_object -return_object controls whether the results of create/update are serialized and returned in the response +Controls whether the results of create/update are serialized and returned in +the response, defaults to false. =cut @@ -234,7 +253,9 @@ has 'return_object' => ( is => 'ro', isa => Bool, default => 0 ); =head1 DESCRIPTION -StaticArguments is a Role that is composed by the controller to provide configuration parameters such as how where in the request data to find specific elements, and if to use JSON boolean types. +StaticArguments is a role that is composed by the controller to provide +configuration parameters such as where to find specific elements in the request +data and if to use JSON boolean types. =cut diff --git a/lib/Catalyst/Controller/DBIC/API/StoredResultSource.pm b/lib/Catalyst/Controller/DBIC/API/StoredResultSource.pm index 6c04d0e..7631654 100644 --- a/lib/Catalyst/Controller/DBIC/API/StoredResultSource.pm +++ b/lib/Catalyst/Controller/DBIC/API/StoredResultSource.pm @@ -10,17 +10,17 @@ use namespace::autoclean; requires '_application'; -=attribute_public class is: ro, isa: Str +=attribute_public class -class is the name of the class that is the model for this controller +The name of the Catalyst model for this controller. =cut has 'class' => ( is => 'ro', isa => Str, writer => '_set_class' ); -=attribute_public result_class is: ro, isa: Str +=attribute_public result_class -result_class is the name of the resultset class that is the model for this controller +Populates the result_class attribute of resultsets. =cut @@ -32,7 +32,7 @@ has 'result_class' => ( =method_public stored_result_source -This is the result source for the controller +Returns the result_source of the stored_model. =cut @@ -42,7 +42,11 @@ sub stored_result_source { =method_public stored_model -This is the model for the controller +Returns the model for the configured class. + +Be aware that model is called as a class method on the Catalyst application +and not as an instance method on $c which might lead to unexpected results +in conjunction with ACCEPT_CONTEXT! =cut