File Coverage

blib/lib/Guardian/OpenPlatform/API.pm
Criterion Covered Total %
statement 18 59 30.5
branch 0 12 0.0
condition 0 11 0.0
subroutine 6 11 54.5
pod 5 5 100.0
total 29 98 29.6


line stmt bran cond sub pod time code
1             =head1 NAME
2            
3             Guardian::OpenPlatform::API - Access the Guardian OpenPlatform API
4            
5             =head1 SYNOPSIS
6            
7             my $api = Guardian::OpenPlatform::API->new({
8             api_key => 'your api key here',
9             });
10            
11             my $resp = $api->content({
12             qry => 'environment',
13             });
14            
15             =head1 DESCRIPTION
16            
17             Guardian::OpenPlatform::API is module which simplifies access to the
18             Guardian's OpenPlatform content API. See
19             L<http://www.guardian.co.uk/open-platform> for more details on the content
20             available.
21            
22             You will need a Guardian developer key in order to use this module. You can
23             get a key from the OpenPlatform web site.
24            
25             =cut
26              
27             package Guardian::OpenPlatform::API;
28              
29 1     1   111002 use strict;
  1         2  
  1         18  
30 1     1   3 use warnings;
  1         0  
  1         19  
31 1     1   17 use 5.006000;
  1         3  
  1         12  
32              
33 1     1   238 use Moose;
  1         265142  
  1         8  
34 1     1   16141 use LWP;
  1         26012  
  1         20  
35 1     1   5 use Carp;
  1         1  
  1         411  
36              
37             our $VERSION = '0.05';
38              
39             my $base_url = 'http://api.guardianapis.com/';
40              
41             has 'ua' => (
42                 is => 'rw',
43                 isa => 'LWP::UserAgent',
44                 );
45              
46             has 'api_key' => (
47                 is => 'rw',
48                 isa => 'Str',
49                 required => 1,
50                 );
51              
52             has 'format' => (
53                 is => 'rw',
54                 isa => 'Str',
55                 default => 'json',
56                 );
57              
58             =head1 METHODS
59            
60             =head2 new({ api_key => $key [, format => '(xml|json)'] })
61            
62             Create a new Guardian::OpenPlatform::API object. Takes a reference to a
63             hash of arguments. This hash has one mandatory key and one optional key.
64            
65             =over 4
66            
67             =item api_key
68            
69             This item is mandatory. The value should be your Guardian API access key.
70            
71             =item format
72            
73             This item is optional. It defines the default format for the data that you
74             get back from the Guardian. Valid values are 'json' or 'xml'. If this
75             argument is omitted then it 'json' is used.
76            
77             =back
78            
79             =head2 content({ qry => $query, [ filter => $filter, format => $fmt ] });
80            
81             Request content from the Guardian. Takes a reference to a hash of arguments.
82             This hash has one mandatory key and two optional keys.
83            
84             =over 4
85            
86             =item qry
87            
88             This item is mandatory. Defines the the text that you want to get data about.
89            
90             =item filter
91            
92             This item is optional. Defines filters to be applied to your query. If you
93             have a single query then the value can be a single scalar value. If you have
94             multiple queries, then the value can be a reference to an array of scalar
95             values.
96            
97             =item format
98            
99             This item is optional. Defines the data format that you want to get back.
100             This can be either 'json' or 'xml'. If no value is given then the default
101             format given to the C<new> method is used.
102            
103             =back
104            
105             This method returns an HTTP::Response object.
106            
107             =cut
108              
109             my %dispatch = (
110                 search => \&search,
111                 tags => \&tags,
112                 item => \&item,
113             );
114              
115             sub content {
116 0     0 1       my $self = shift;
117              
118 0               my $args = shift;
119              
120 0   0           my $mode = $args->{mode} || 'search';
121              
122 0 0             croak "Invalid mode '$mode'" unless exists $dispatch{$mode};
123              
124 0               my $method = $dispatch{$mode};
125              
126 0               $self->$method($args);
127             }
128              
129             =head2 search({ qry => $query, [ filter => $filter, format => $fmt ] });
130            
131             Currently does the same as C<content>. Will get more complex though.
132            
133             =cut
134              
135             sub search {
136 0     0 1       my $self = shift;
137              
138 0               my $args = shift;
139              
140 0               my $url = $base_url . "content/search?q=$args->{qry}";
141              
142 0 0             if ($args->{filter}) {
143 0 0         unless (ref $args->{filter}) {
144 0           $url .= "&filter=$args->{filter}";
145             }
146              
147 0 0         if (ref $args->{filter} eq 'ARRAY') {
148 0           foreach (@{$args->{filter}}) {
  0            
149 0           $url .= "&filter=$_";
150             }
151             }
152                 }
153              
154 0   0           my $fmt = $args->{format} || $self->format;
155 0               $url .= "&format=$fmt";
156              
157 0               $url .= '&api_key=' . $self->api_key;
158              
159 0               my $resp = $self->{ua}->get($url);
160             }
161              
162             =head2 tags
163            
164             Returns information about tags.
165            
166             =cut
167              
168             sub tags {
169 0     0 1       my $self = shift;
170              
171 0               my $args = shift;
172              
173 0               my $url = $base_url . 'content/tags';
174              
175 0               my $params;
176 0 0             if ($args->{qry}) {
177 0                   $url .= "?q=$args->{qry}";
178 0                   $params = 1;
179                 }
180              
181 0   0           my $fmt = $args->{format} || $self->format;
182              
183 0 0             $url .= $params ? '&' : '?';
184 0               $url .= "format=$fmt";
185              
186 0               $url .= '&api_key=' . $self->api_key;
187              
188 0               my $resp = $self->{ua}->get($url);
189             }
190              
191             =head2 item
192            
193             Returns a content item given its id.
194            
195             =cut
196              
197             sub item {
198 0     0 1       my $self = shift;
199              
200 0               my $args = shift;
201              
202 0               my $url = $base_url . "content/item/$args->{item}";
203              
204 0   0           my $fmt = $args->{format} || $self->format;
205              
206 0               $url .= "?format=$fmt";
207              
208 0               $url .= '&api_key=' . $self->api_key;
209              
210 0               my $resp = $self->{ua}->get($url);
211             }
212              
213             =head2 BUILD
214            
215             Standard Moose BUILD method. You shouldn't need to call this.
216            
217             =cut
218              
219             sub BUILD {
220 0     0 1       my $self = shift;
221              
222 0               $self->{ua} = LWP::UserAgent->new;
223             }
224              
225             =head1 TODO
226            
227             This is really just a simple proof of concept. It will get better, I promise.
228            
229             =head1 BUGS, REQUESTS, COMMENTS
230            
231             Support for this module is supplied using the CPAN RT system via the web or
232             email:
233            
234             L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Guardian::OpenPlatform::API>
235            
236             bug-guardian-openplatform-api@rt.cpan.org
237            
238             This makes it much easier for me to track things and thus means your problem
239             is less likely to be neglected.
240            
241             =head1 SOURCE CODE
242            
243             Source code for this module is available on GitHub at
244            
245             =over 4
246            
247             =item *
248            
249             http://github.com/davorg/guardian-openplatform-api/
250            
251             =back
252            
253             Please feel free to clone, fork and otherwise play with it.
254            
255             =head1 LICENCE AND COPYRIGHT
256            
257             Copyright (c) Magnum Solutions Ltd., 2009. All rights reserved.
258            
259             This library is free software; you can redistribute it and/or modify it under
260             the same terms as Perl itself, either Perl version 5.000 or, at your option,
261             any later version of Perl 5 you may have available.
262            
263             The full text of the licences can be found in perlartistic and perlgpl as
264             supplied with Perl 5.8.1 and later.
265            
266             =head1 AUTHOR
267            
268             Dave Cross, E<lt>dave@mag-sol.comE<gt>
269            
270             =cut
271              
272             1;
273