# NAME Spica - the HTTP client for dealing with complex WEB API. # SYNOPSIS my $spica = Spica->new( host => 'example.com', spec => 'Example::Spec', ); my $iterator = $spica->fetch(client => 'list' => +{key => $value}); # DESCRIPTION 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. # SIMPLEST CASE create Spica's instance. arguments `host` must be required. fetch returned object is `Spica::Receiver::Iterator`. my $spica = Spica->new( host => 'example.com' ); my $iterator = $spica->fetch('/users', +{ rows => 20, }); # THE BASIC USAGE create specifiction class. see `Spica::Spec` for docs on defining spec class. 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; } # ARCHITECTURE Spica iclasses are comprised of following distinct components: ## CLIENT `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`. ## 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. 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 `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` 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 `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`. # METHODS Spica provides a number of methods to all your classes, ## $spica = Spica->new(%args) 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. - `host` :Str This is the URI hostname of WEB API. This argument is always required. - `port` :Int This is the URI port of WEB API. By default, `80` is used. - `agent` :Str This is the Fetcher agent name of Spica. By default, `Spica $VERSION` is used. - `default_param` :HashRef You can specify the parameters common to request the WEB API. - `default_headers` :ArrayRef You can specify the headers common to request the WEB API. - `spec` `spec` expecs the name of the class that inherits `Spiac::Spec`. By default, `spec` is not used. - `parser` `parser` expects the name of the class that inherits `Spica::Parser`. By default, `Spica::Parser::JSON` is used. - `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. - `no_throw_http_exception` Specifies the mode that does not throw the exception of HTTP. by default this value is `false`. ## $iterator = $spica->fetch(@args); Request to the WEB API, to build the object. I have the interface of the following three: ### $spica->fetch($client\_name, $endpoint\_name, $param) It is the access method basic. Arguments can be: - `client_name` : Str Enter the name of the client that you have defined in `spec`. - `endpoint_name` : Str Enter the name of `endpoint` that is defined in the `client`. - `param` : HashRef Specified in `HashRef` the content and query parameters required to request. I will specify the HashRef empty if there are no parameters. ### $spica->fetch($client\_name, $param) You can omit the `endpoint_name` of `fetch` If you specify a string of `default` to `name` of . Arguments can be: - `client_name` : Str - `param` : HashRef ### $spica->fetch($path, $param) You can request by specifying to fetch the If you do not specify the `spec`. Arguments can be: - `path` : Str - `param` : HashRef # SEE ALSO # AUTHOR mizuki\_r # REPOSITORY git clone git@github.com:rymizuki/p5-Spica.git # LICENCE AND COPYRIGHT Copyright (c) 2013, the Spica ["AUTHOR"](#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](http://search.cpan.org/perldoc?perlartistic).