ryo iinuma
and 1 contributors


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.

    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.

    package Your::API::Spec;
    use Spica::Spec::Declare;

    client {
        name 'example';
        endpoint list => '/users' => [];
        columns qw( id name message );


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.


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(

    ... 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

    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);


in your script

    my $spica = Spica->new(%args);



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 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:


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 expecs the name of the class that inherits Spiac::Spec. By default, spec is not used.


parser expects the name of the class that inherits Spica::Parser. By default, Spica::Parser::JSON is used.


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.


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 <endpoint>.

Arguments can be:

client_name : Str
param : HashRef

$spica->fetch($path, $param)

You can request by specifying to fetch the <path> If you do not specify the spec.

Arguments can be:

path : Str
param : HashRef



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.