Spica - the HTTP client for dealing with complex WEB API.
my $spica = Spica->new( host => 'example.com', spec => 'Example::Spec', ); my $iterator = $spica->fetch(client => 'list' => +{key => $value});
Spica provides an interface to common WEB API many. It is the HTTP Client that combines the flexibility and scalability of a O/R Mapper and Model of Backbone.js.
create Spica's instance. arguments host must be required. fetch returned object is Spica::Receiver::Iterator.
host
Spica::Receiver::Iterator
my $spica = Spica->new( host => 'example.com' ); my $iterator = $spica->fetch('/users', +{ rows => 20, });
create specifiction class. see Spica::Spec for docs on defining spec class.
Spica::Spec
package Your::API::Spec; use Spica::Spec::Declare; client { name 'example'; endpoint list => '/users' => []; columns qw( id name message ); }; 1;
in your script.
use Spica; my $spica = Spica->new( host => 'example.com', spec => 'Your::API::Spec', ); # fetching WEB API. my $iterator = $spca->fetch('example', 'list', +{}); while (my $user = $iterator->next) { say $user->name; }
Spica iclasses are comprised of following distinct components:
client is a class with information about how to receipt of the request parameter data for WEB API. client uses Spica::Spec::Iterator the receipt of data and GET request as the initial value, but I can cope with a wide range of API specification by extending in spec.
client
Spica::Spec::Iterator
spec
The spec is a simple class that describes specifictions of the WEB API. spec is a simple class that describes the specifications of the WEB API. You can extend the client by changing the receiver class you can specify the HTTP request other than GET request.
receiver
package Your::Spec; use Spica::Spec::Declare; client { name 'example'; endpoint 'name1', '/path/to', [qw(column1 column2)]; endpoint 'name2', '/path/to/{replace}, [qw(replace_column column)]; endpoint 'name3', +{ method => 'POST', path => '/path/to', requires => [qw(column1 column2)], }; columns qw( column1 column2 ); } ... and other clients ...
parser is a class for to be converted to a format that can be handled in Perl format that the API provides. You can use an API of its own format if you extend the Spica::Parser
parser
Spica::Parser
package Your::Parser; use parent qw(Spica::Parser); use Data::MessagePack; sub parser { my $self = shift; return $self->{parser} ||= Data::MessagePack->new; } sub parse { my ($self, $body) = @_; return $self->parser->unpack($body); } 1;
in your script
my $spica = Spica->new(%args); $spica->parser('Your::Parser');
receiver is a class for easier handling more data received from the WEB API. receiver This contains the Spica::Receiver::Row and Spica::Receiver::Iterator.
Spica::Receiver::Row
Spica provides a number of methods to all your classes,
Creates a new Spica instance.
my $spica = Spica->new( host => 'example.com', spec => 'Your::Spec', );
Arguments can be:
scheme
This is the URI scheme of WEB API. By default, http is used.
http
This is the URI hostname of WEB API. This argument is always required.
port
This is the URI port of WEB API. By default, 80 is used.
80
agent
This is the Fetcher agent name of Spica. By default, Spica $VERSION is used.
Spica $VERSION
default_param
You can specify the parameters common to request the WEB API.
default_headers
You can specify the headers common to request the WEB API.
spec expecs the name of the class that inherits Spiac::Spec. By default, spec is not used.
Spiac::Spec
parser expects the name of the class that inherits Spica::Parser. By default, Spica::Parser::JSON is used.
Spica::Parser::JSON
is_suppress_object_creation
Specifies the receiver object creation mode. By default this value is false. If you specifies this to a true value, no row object will be created when a receive on WEB API results.
false
true
no_throw_http_exception
Specifies the mode that does not throw the exception of HTTP. by default this value is false.
Request to the WEB API, to build the object. I have the interface of the following three:
It is the access method basic.
client_name
Enter the name of the client that you have defined in spec.
endpoint_name
Enter the name of endpoint that is defined in the client.
endpoint
param
Specified in HashRef the content and query parameters required to request. I will specify the HashRef empty if there are no parameters.
HashRef
You can omit the endpoint_name of fetch If you specify a string of default to name of <endpoint>.
fetch
default
name
You can request by specifying to fetch the <path> If you do not specify the spec.
path
mizuki_r <ry.mizuki@gmail.com>
git clone git@github.com:rymizuki/p5-Spica.git
Copyright (c) 2013, the Spica "AUTHOR". All rights reserved.
This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See perlartistic.
To install Spica, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Spica
CPAN shell
perl -MCPAN -e shell install Spica
For more information on module installation, please visit the detailed CPAN module installation guide.