/ 
Spica-0.04
River stage zero No dependents
/ Spica

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

SEE ALSO

AUTHOR

mizuki_r <ry.mizuki@gmail.com>

REPOSITORY

git clone git@github.com:rymizuki/p5-Spica.git

LICENCE AND COPYRIGHT

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.