File Coverage

blib/lib/Dancer/Plugin/RESTModel.pm
Criterion Covered Total %
statement 7 9 77.7
branch n/a
condition n/a
subroutine 3 3 100.0
pod n/a
total 10 12 83.3


line stmt bran cond sub pod time code
1             package Dancer::Plugin::RESTModel;
2 2     2   56930 use strict;
  2         5  
  2         91  
3 2     2   12 use warnings;
  2         4  
  2         61  
4              
5 2     2   2326 use Moose;
  0            
  0            
6             with 'Role::REST::Client';
7              
8             use Dancer qw( :syntax :moose );
9             use Dancer::Plugin;
10             use Carp 'croak';
11              
12             our $VERSION = 0.02;
13              
14             my $schemas = {};
15              
16             register model => sub {
17             my (undef, $name) = plugin_args(@_);
18             return $schemas->{$name} if exists $schemas->{$name};
19              
20             my $conf = plugin_setting;
21             my $options = $conf->{$name}
22             or croak "The schema '$name' is not configured";
23              
24             my $model = __PACKAGE__->new( %{$conf->{$name}} );
25             $schemas->{$name} = $model;
26              
27             return $model;
28             };
29              
30             __PACKAGE__->meta->make_immutable;
31              
32             register_plugin;
33             42;
34             __END__
35              
36             =head1 NAME
37              
38             Dancer::Plugin::RESTModel - REST model class for Dancer apps
39              
40              
41             =head1 SYNOPSIS
42              
43             set the REST endpoint in your Dancer configuration file:
44              
45             plugins:
46             RESTModel:
47             MyData:
48             server: http://localhost:5000
49             type: application/json
50             clientattrs:
51             timeout: 5
52              
53             then use it from any of your routes/controllers:
54              
55             use Dancer ':syntax';
56             use Dancer::Plugin::RESTModel;
57              
58             get '/' => sub {
59             my $res = model('MyData')->post( 'foo/bar/baz', { meep => 'moop' } );
60              
61             my $code = $res->code; # e.g. 200
62             my $data = $res->data;
63              
64             ...
65             };
66              
67              
68             =head1 DESCRIPTION
69              
70             This plugin lets you talk to a REST server as a separate model from within
71             your Dancer app. It is useful for keeping your API decoupled from your app
72             while still being able to manage it through the configuration file.
73              
74             It is a thin wrapper over L<Role::REST::Client>.
75              
76             =head1 INTERFACE
77              
78             =head2 model()
79              
80             The exported C<model()> function returns a REST Model object which provides
81             the standard HTTP 1.1 verbs as methods:
82              
83             post
84             get
85             put
86             delete
87             options
88             head
89              
90             All methods take these parameters:
91              
92             =over 4
93              
94             =item * url - the REST service being accessed
95              
96             =item * data - The data structure to send (hashref, arrayref). The data will
97             be encoded according to the value of the I<type> attribute
98              
99             =item * args - B<optional> hashref with arguments to augment the way the call
100             is handled. It currently provides the 'deserializer' key to change the
101             deserializer if you I<know> that the response's content-type is incorrect,
102             and also the 'preserve_headers' which, if set to true, will keep the headers
103             between calls:
104              
105             my $res = model('MyData')->post(
106             'users/123',
107             { foo => 'bar' },
108             { deserializer => 'application/yaml', preserve_headers => 1 },
109             );
110              
111             =back
112              
113             The third parameter, I<args>, is an optional hashref which lets you give
114             extra information to the object. It currently provides
115              
116             =head1 CONFIGURATION AND ENVIRONMENT
117              
118             =head2 server
119              
120             =head2 type
121              
122             =head2 user_agent
123              
124             =head2 httpheaders
125              
126             =head2 persistent_headers
127              
128             =head2 clientattrs
129              
130              
131             =head1 BUGS AND LIMITATIONS
132              
133             Please report any bugs or feature requests to
134             C<bug-dancer-plugin-restmodel@rt.cpan.org>, or through the web interface at
135             L<http://rt.cpan.org>.
136              
137             =head1 SEE ALSO
138              
139             =over 4
140              
141             =item L<Dancer::Plugin::REST>
142              
143             =item L<Role::REST::Client>
144              
145             =item L<Dancer>
146              
147             =back
148              
149             =head1 AUTHOR
150              
151             Breno G. de Oliveira C<< <garu@cpan.org> >>
152              
153              
154             =head1 LICENCE AND COPYRIGHT
155              
156             Copyright (c) 2013-2014, Breno G. de Oliveira C<< <garu@cpan.org> >>. All rights reserved.
157              
158             This module is free software; you can redistribute it and/or
159             modify it under the same terms as Perl itself. See L<perlartistic>.
160              
161              
162             =head1 DISCLAIMER OF WARRANTY
163              
164             BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
165             FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN
166             OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
167             PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER
168             EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
169             WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE
170             ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH
171             YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL
172             NECESSARY SERVICING, REPAIR, OR CORRECTION.
173              
174             IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
175             WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
176             REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE
177             LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL,
178             OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE
179             THE SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
180             RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A
181             FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF
182             SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
183             SUCH DAMAGES.