NAME

Net::HTTP::Knork - Lightweight implementation of Spore specification

VERSION

version 0.08

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

responses are HTTP::Response objects

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 : options to pass to the 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_url});
    $client->$post_foo(payload => { bar => 'baz' });

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.

TODO

This is still early alpha code but there are still some things missing :

debug mode

more tests

a real life usage

BUGS

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

ACKNOWLEDGEMENTS

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

AUTHOR

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