NAME

Net::HTTP::Knork - Spore without the whistles and the bells

VERSION

version 0.07

SYNOPSIS

use strict; 
use warnings; 
use Net::HTTP::Knork;
use JSON;
my $spec = to_json(
    {   version => 1,
        format  => [ "json", ],
        methods => {
            test => {
                method => 'GET',
                path   => '/test/:foo',
                required_params => [ "foo" ],
            }
        }
        base_url => 'http://example.com',
    }
);

my $knork = Net::HTTP::Knork->new(spec => $spec);

# make a GET to 'http://example.com/test/bar'
my $resp = $knork->test({ foo => bar}); 

DESCRIPTION

Net::HTTP::Knork is a module that aims to be compatible with the Spore specification. So it is like Net::HTTP::Spore but with some differences:

Moo instead of Moose

specifications can be either JSON (a string or a file) or a plain Perl hash

specifications are validated with Data::Rx

no real middleware support as in Spore, though there are some workarounds

MIDDLEWARES

Usage

use strict; 
use warnings; 
use JSON; 
use Net::HTTP::Knork; 
# create a client with a middleware that encode requests to json and
# decode responses from json 
my $client = Net::HTTP::Knork->new(spec => '/path/to/spec.json');
$client->add_middleware(
    {   on_request => sub {
            my $self = shift;
            my $req = shift;
            $req->header( 'Content-Type' => 'application/json' );
            $req->header( 'Accept'       => 'application/json' );
            $req->content( $json->encode( $req->content ) );
            return $req;
        },
        on_response => sub {
            my $self = shift;
            my $resp = shift;
            $resp->content( $json->decode( $resp->content ) );
            return $resp;
          }
    }
);

Although middlewares cannot be created as in Net::HTTP::Spore, there is still the possibility to declare subs that will be executed either on requests or responses. To accomplish this, it installs modifiers around some core functions in Net::HTTP::Knork, using Class::Method::Modifiers.

Limitations

Basic

The system is kind of rough on edges. It should match simple needs, but for complex middlewares it would need a lot of code.

Order of application

The last middleware applicated will always be the first executed.

METHODS

new

Creates a new Knork object.

my $client = Net::HTTP::Knork->new(spec => '/some/file.json');
# or 
my $client = Net::HTTP::Knork->new(spec => $a_perl_hash); 
# or 
my $client = Net::HTTP::Knork->new($spec => $a_json_object);

Other constructor options:

- default_params:  hash specifying default parameters to pass on every requests.

  # pass foo=bar on every request 
  my $client = Net::HTTP::Knork->new(spec => 'some_file.json', default params => {foo => bar}); 

 - http_options : ptions to pass to the L<LWP::UserAgent> used as a backend for Knork. 

make_sub_from_spec

Creates a new Knork sub from a snippet of spec. You might want to do that if you want to create new subs with parameters you can get on runtime, while maintaining all the benefits of using Knork.

my $client = Net::HTTP::Knork->new(spec => '/some/file.json');
my $response = $client->get_foo_url(); 
my $foo_url = $response->body->{foo_url}; 
my $post_foo = $client->make_sub_from_spec({method => 'POST', path => '/foo'});
$client->$post_foo(payload => { bar => baz });

BUGS

This code is early alpha, so there will be a whole bucket of bugs.

ACKNOWLEDGEMENTS

Thank you to Franck Cuny, the originator of Net::HTTP::Spore. Some parts of this module borrow code from his module.

AUTHOR

Emmanuel "BHS_error" Peroumalnaik

COPYRIGHT AND LICENSE

This software is copyright (c) 2014 by E. Peroumalnaik.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.