Spica is the HTTP client for dealing with complex WEB API
Latest commit c00f0ff Nov 12, 2013 @rymizuki rymizuki Checking in changes prior to tagging of version 0.04.
Changelog diff is:

diff --git a/Changes b/Changes
index c4bc44c..31ee362 100644
--- a/Changes
+++ b/Changes
@@ -2,6 +2,9 @@ Revision history for Perl extension Spica


+0.04 2013-11-12T12:50:03Z
+    - fixed issues #20
 0.03 2013-10-22T11:43:53Z

     - to change the specifications of the trigger



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:

  • 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



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.