/XML-OverHTTP/README

  1NAME
  2    XML::OverHTTP - A base class for XML over HTTP-styled web service
  3    interface
  4
  5DESCRIPTION
  6    This module is not used directly from end-users. As a child class of
  7    this, module authors can easily write own interface module for XML over
  8    HTTP-styled web service.
  9
 10METHODS PROVIDED
 11    This module provides some methods and requires other methods overridden
 12    by child classes. The following methods are to be called in your module
 13    or by its users.
 14
 15  new
 16    This constructor method returns a new object for your users. It accepts
 17    query parameters by hash.
 18
 19        my $api = MyAPI->new( %param );
 20
 21    MyAPI.pm inherits this XML::OverHTTP modules.
 22
 23  add_param
 24    This method adds query parameters for the request.
 25
 26        $api->add_param( %param );
 27
 28    It does not validate key names.
 29
 30  get_param
 31    This method returns a current query parameter.
 32
 33        $api->get_param( 'key' );
 34
 35  treepp
 36    This method returns an XML::TreePP object to make the request.
 37
 38        $api->treepp->get( 'key' );
 39
 40    And you can set its object as well.
 41
 42        my $mytpp = XML::TreePP->new;
 43        $api->treepp( $mytpp );
 44
 45    total_entries, entries_per_page and current_page parameters in $mytpp
 46    are updated.
 47
 48  request
 49    This method makes the request for the web service and returns its
 50    response tree.
 51
 52        my $tree = $api->request;
 53
 54    After calling this method, the following methods are available.
 55
 56  tree
 57    This method returns the whole of the response parsed by XML::TreePP
 58    parser.
 59
 60        my $tree = $api->tree;
 61
 62    Every element is blessed when "elem_class" is defined.
 63
 64  root
 65    This method returns the root element in the response.
 66
 67        my $root = $api->root;
 68
 69  xml
 70    This method returns the response context itself.
 71
 72        print $api->xml, "\n";
 73
 74  code
 75    This method returns the response status code.
 76
 77        my $code = $api->code; # usually "200" when succeeded
 78
 79  page
 80    This method returns a Data::Page object to create page navigation.
 81
 82        my $pager = $api->page;
 83        print "Last page: ", $pager->last_page, "\n";
 84
 85    And you can set its object as well.
 86
 87        my $pager = Data::Page->new;
 88        $api->page( $pager );
 89
 90  pageset
 91    This method returns a Data::Pageset object to create page navigation.
 92    The paging mode is "fixed" as default.
 93
 94        my $pager = $api->pageset;
 95        $pager->pages_per_set( 10 );
 96        print "First page of next page set: ",  $page_info->next_set, "\n";
 97
 98    Or set it to "slide" mode if you want.
 99
100        my $pager = $api->pageset( 'slide' );
101
102  page_param
103    This method returns pair(s) of query key and value to set the page
104    number for the next request.
105
106        my $hash = $api->page_param( $page );
107
108    The optional second argument specifies the number of entries per page.
109
110        my $hash = $api->page_param( $page, $size );
111
112    The optional third argument incluedes some other query parameters.
113
114        my $newhash = $api->page_param( $page, $size, $oldhash );
115
116  page_query
117    This method returns a processed query string which is joined by '&'
118    delimiter.
119
120        my $query = $api->page_query();                         # current page
121        my $query = $api->page_query( $page, $size, $hash );    # specified page
122
123METHOD YOU MUST OVERRIDE
124    You MUST override at least one method below:
125
126  url
127    This is a method to specify the url for the request to the web service.
128    E.g.,
129
130        sub url { 'http://www.example.com/api/V1/' }
131
132METHODS YOU SHOULD OVERRIDE
133    The methods that you SHOULD override in your module are below:
134
135  root_elem
136    This is a method to specify a root element name in the response. E.g.,
137
138        sub root_elem { 'rdf:RDF' }
139
140  is_error
141    This is a method to return "true" value when the response seems to have
142    error. This returns "undef" when it succeeds. E.g.,
143
144        sub is_error { $_[0]->root->{status} != 'OK' }
145
146  total_entries
147    This is a method to return the number of total entries for "Data::Page".
148    E.g.,
149
150        sub total_entries { $_[0]->root->{hits} }
151
152  entries_per_page
153    This is a method to return the number of entries per page for
154    "Data::Page". E.g.,
155
156        sub entries_per_page { $_[0]->root->{-count} }
157
158  current_page
159    This is a method to return the current page number for "Data::Page".
160    E.g.,
161
162        sub current_page { $_[0]->root->{-page} }
163
164  page_param
165    This is a method to return paging parameters for the next request. E.g.,
166
167        sub page_param {
168            my $self = shift;
169            my $page = shift || $self->current_page();
170            my $size = shift || $self->entries_per_page();
171            my $hash = shift || {};
172            $hash->{page}  = $page if defined $page;
173            $hash->{count} = $size if defined $size;
174            $hash;
175        }
176
177    When your API uses SQL-like query parameters, offset and limit:
178
179        sub page_param {
180            my $self = shift;
181            my $page = shift || $self->current_page() or return;
182            my $size = shift || $self->entries_per_page() or return;
183            my $hash = shift || {};
184            $hash->{offset} = ($page-1) * $size;
185            $hash->{limit}  = $size;
186            $hash;
187        }
188
189METHODS YOU CAN OVERRIDE
190    You CAN override the following methods as well.
191
192  http_method
193    This is a method to specify the HTTP method, 'GET' or 'POST', for the
194    request. This returns 'GET' as default. E.g.,
195
196        sub http_method { 'GET' }
197
198  default_param
199    This is a method to specify pairs of default query parameter and its
200    value for the request. E.g.,
201
202        sub default_param { { method => 'search', lang => 'perl' } }
203
204  notnull_param
205    This is a method to specify a list of query parameters which are
206    required by the web service. E.g.,
207
208        sub notnull_param { [qw( api_key secret query )] }
209
210    These keys are checked before makeing a request for safe.
211
212  query_class
213    This is a method to specify a class name for query parameters. E.g.,
214
215        sub elem_class { 'MyAPI::Query' }
216
217    The default value is "undef", it means a normal hash is used instead.
218
219  attr_prefix
220    This is a method to specify a prefix for each attribute in the response
221    tree. XML::TreePP uses it. E.g.,
222
223        sub attr_prefix { '' }
224
225    The default prefix is zero-length string "" which is recommended.
226
227  text_node_key
228    This is a method to specify a hash key for text nodes in the response
229    tree. XML::TreePP uses it. E.g.,
230
231        sub text_node_key { '_text' }
232
233    The default key is "#text".
234
235  elem_class
236    This is a method to specify a base class name for each element in the
237    response tree. XML::TreePP uses it. E.g.,
238
239        sub elem_class { 'MyAPI::Element' }
240
241    The default value is "undef", it means each elements is a just hashref
242    and not bless-ed.
243
244  force_array
245    This is a method to specify a list of element names which should always
246    be forced into an array representation in the response tree. XML::TreePP
247    uses it. E.g.,
248
249        sub force_array { [qw( rdf:li item xmlns )] }
250
251  force_hash
252    This is a method to specify a list of element names which should always
253    be forced into an hash representation in the response tree. XML::TreePP
254    uses it. E.g.,
255
256        sub force_hash { [qw( item image )] }
257
258SEE ALSO
259    XML::TreePP
260
261    <http://www.kawa.net/works/perl/overhttp/overhttp-e.html>
262
263AUTHOR
264    Yusuke Kawasaki <http://www.kawa.net/>
265
266COPYRIGHT AND LICENSE
267    Copyright (c) 2007 Yusuke Kawasaki. All rights reserved. This program is
268    free software; you can redistribute it and/or modify it under the same
269    terms as Perl itself.
270