File Coverage

blib/lib/Guardian/OpenPlatform/API.pm
Criterion Covered Total %
statement 20 61 32.7
branch 0 12 0.0
condition 0 11 0.0
subroutine 7 12 58.3
pod 5 5 100.0
total 32 101 31.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   12874 use strict;
  1         1  
  1         23  
30 1     1   3 use warnings;
  1         1  
  1         25  
31 1     1   14 use 5.006000;
  1         4  
32              
33 1     1   444 use Moo;
  1         8976  
  1         4  
34 1     1   1486 use namespace::clean;
  1         8198  
  1         2  
35              
36 1     1   613 use LWP;
  1         30064  
  1         24  
37 1     1   5 use Carp;
  1         2  
  1         456  
38              
39             our $VERSION = '0.07';
40              
41             my $base_url = 'http://content.guardianapis.com/';
42              
43             has 'ua' => (
44             is => 'rw',
45             isa => sub { die 'Need LWP::UserAgent object' unless (ref($_[0]) eq 'LWP::UserAgent'); }
46             );
47              
48             has 'api_key' => (
49             is => 'rw',
50             required => 1,
51             );
52              
53             has 'format' => (
54             is => 'rw',
55             default => sub { 'json' },
56             );
57              
58             =head1 METHODS
59              
60             =head2 new({ api_key => $key [, format => '(xml|json)'] })
61              
62             Create a new L<Guardian::OpenPlatform::API> object.Takes a reference to a hash of
63             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 an optional. It defines the default format for the data that you get
74             back from the Guardian. Valid values are 'json' or 'xml'. Default is 'json'.
75              
76             =back
77              
78             =head2 content({ qry => $query, [ filter => $filter, format => $fmt ] });
79              
80             Request content from the Guardian. Takes a reference to a hash of arguments. This
81             hash has one mandatory key and two optional keys.
82              
83             =over 4
84              
85             =item qry
86              
87             This item is mandatory. Defines the the text that you want to get data about.
88              
89             =item filter
90              
91             This item is optional. Defines filters to be applied to your query. If you have a
92             single query then the value can be a single scalar value. If you have multiple
93             queries, then the value can be a reference to an array of scalar values.
94              
95             =item format
96              
97             This item is optional. Defines the data format that you want to get back.This can
98             be either 'json' or 'xml'. If no value is given then the default format given to
99             the C<new> method is used.
100              
101             =back
102              
103             This method returns an HTTP::Response object.
104              
105             =cut
106              
107             my %dispatch = (
108             search => \&search,
109             tags => \&tags,
110             item => \&item,
111             );
112              
113             sub content {
114 0     0 1   my $self = shift;
115              
116 0           my $args = shift;
117              
118 0   0       my $mode = $args->{mode} || 'search';
119              
120 0 0         croak "Invalid mode '$mode'" unless exists $dispatch{$mode};
121              
122 0           my $method = $dispatch{$mode};
123              
124 0           $self->$method($args);
125             }
126              
127             =head2 search({ qry => $query, [ filter => $filter, format => $fmt ] });
128              
129             Currently does the same as C<content>. Will get more complex though.
130              
131             =cut
132              
133             sub search {
134 0     0 1   my $self = shift;
135 0           my $args = shift;
136              
137 0           my $url = $base_url . "search?q=$args->{qry}";
138              
139 0 0         if ($args->{filter}) {
140 0 0         unless (ref $args->{filter}) {
141 0           $url .= "&filter=$args->{filter}";
142             }
143              
144 0 0         if (ref $args->{filter} eq 'ARRAY') {
145 0           foreach (@{$args->{filter}}) {
  0            
146 0           $url .= "&filter=$_";
147             }
148             }
149             }
150              
151 0   0       my $fmt = $args->{format} || $self->format;
152 0           $url .= "&format=$fmt";
153 0           $url .= '&api-key=' . $self->api_key;
154              
155 0           my $resp = $self->{ua}->get($url);
156             }
157              
158             =head2 tags(\%params)
159              
160             Returns information about tags.
161              
162             =cut
163              
164             sub tags {
165 0     0 1   my $self = shift;
166 0           my $args = shift;
167              
168 0           my $url = $base_url . 'tags';
169 0           my $params;
170 0 0         if ($args->{qry}) {
171 0           $url .= "?q=$args->{qry}";
172 0           $params = 1;
173             }
174              
175 0   0       my $fmt = $args->{format} || $self->format;
176              
177 0 0         $url .= $params ? '&' : '?';
178 0           $url .= "format=$fmt";
179              
180 0           $url .= '&api-key=' . $self->api_key;
181              
182 0           my $resp = $self->{ua}->get($url);
183             }
184              
185             =head2 item(\%params)
186              
187             Returns a content item given its id.
188              
189             =cut
190              
191             sub item {
192 0     0 1   my $self = shift;
193 0           my $args = shift;
194              
195 0           my $url = $base_url . "item/$args->{item}";
196 0   0       my $fmt = $args->{format} || $self->format;
197              
198 0           $url .= "?format=$fmt";
199 0           $url .= '&api-key=' . $self->api_key;
200              
201 0           my $resp = $self->{ua}->get($url);
202             }
203              
204             =head2 BUILD
205              
206             Standard Moose BUILD method. You shouldn't need to call this.
207              
208             =cut
209              
210             sub BUILD {
211 0     0 1   my $self = shift;
212              
213 0           $self->{ua} = LWP::UserAgent->new;
214             }
215              
216             =head1 TODO
217              
218             This is really just a simple proof of concept. It will get better, I promise.
219              
220             =head1 BUGS, REQUESTS, COMMENTS
221              
222             Support for this module is supplied using the CPAN RT system via the web / email:
223              
224             L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Guardian::OpenPlatform::API>
225              
226             bug-guardian-openplatform-api@rt.cpan.org
227              
228             This makes it much easier for me to track things and thus means your problem is
229             less likely to be neglected.
230              
231             =head1 REPOSITORY
232              
233             L<https://github.com/manwar/guardian-openplatform-api>
234              
235             =head1 LICENCE AND COPYRIGHT
236              
237             Copyright (c) Magnum Solutions Ltd., 2009. All rights reserved.
238              
239             This library is free software; you can redistribute it and/or modify it under the
240             same terms as Perl itself, either Perl version 5.000 or, at your option,any later
241             version of Perl 5 you may have available.
242              
243             The full text of the licences can be found in perlartistic and perlgpl as supplied
244             with Perl 5.8.1 and later.
245              
246             =head1 AUTHOR
247              
248             Dave Cross, E<lt>dave@mag-sol.comE<gt>
249              
250             Currently maintained by Mohammad S Anwar, C<< <mohammad.anwar at yahoo.com> >>
251              
252             =cut
253              
254             1;