NAME

Hyle

DESCRIPTION

Simple REST API interface to the database backend using Plack and DBIx::Class

WARNING: This is APLHA quality software.

SYNOPSIS

    # cpanm Hyle

    # echo "CREATE TABLE cds (id int not null, title varchar);" | sqlite3 /tmp/foo.db

    # hyle.pl  --dsn'dbi::SQLite::dbname=/tmp/foo.db'
    # HTTP::Server::PSGI: Accepting connections at http://0:5000/
    # ...

    # curl -X PUT --data'id:1&=title=someTitle' http://localhost:5000/cds/

    # curl http://localhost:5000/cds/id/7

    # curl -X GET,DELETE,POST

    # more configuration 
    my $schema = DBIx::Class->connect(...);

    my $app = Hyle->new(
        schema => $schema,
        ... other options ...
    );

    # make a custom mount with Plack::Builder

    builder {
        mount => "/somewhere" => $app;
        mount => /somethingElse" => $other_app;
    };

Default REST methods implementations for

GET

POST

PUT

DELETE

HEAD

OBJECT ATTRIBUTES

The Hyle object can be provided a number of attributes, they're all in the format of : hashkey => HASHREF. All of those parameters are optional.

serializers

    %serializers = (
        "application/json" => sub { ... },
        ...,
    );

defaults to 'data/json', response content type and JSON::encode_json serialization function if no serializers are provided.

override

    %overrides = (
        'artist' => { GET => sub { ... } },
        ...,
    );

allows overriding of default actions per resultset.

You can also subclass the Hyle class or provide default REST methods overrides in particular ResultSource class.

The app is going to try the following things when looking for an appropriate REST method implementation to dispatch to or a given resultset/ database table.

if the ResultSource class itself implements the __GET() __POST() __DELETE etc., methods, those will be invoked first, then followed by the check for an appropriate method in the %overrides hash, if no method is found, the default ( Hyle::__GET, etc.) implementation will be used.

validator

This optional subroutine reference receives a Plack::Request object and is expected to return either true or false, which determines whether a given request is to be handled or refused.

result_sources

    %result_sources = (
        artist => 1,
        cds    => 1,
        ...
    );

Expose only the following result sources in the api.

Support for JSONP

It's possible to add code that will be handled as jsonp call, i.e.:

    my $jsonp_method = sub {
        my ($self,$req,$resultset,$rs,$jsonp_method_name,@args) = @_;

        $rs->search_where({
            column => { -in => [ \@args ] },
        });

        # ....
        my $response = $req->new_response(200);
        $response->body( $self->serializer( ... ) );
    };

    my $app = Hyle->new(
        schema   => $schema,
        override => {
            cds => { jsonp_method_name => $jsonp_method },
        },
    );

The method can also be declared inside of the particulat DBIC ResultSource class. In that case however, the application will only accept methods that have subroutine attribute of 'JSONP", i.e.:

   sub DoSomethhingElse :JSONP {
        my ($self,$req,$resultset,$rs,$jsonp_method_name,@args) = @_;
        ...;
   }

The application can also advertise jsonp method alongside the data returned by GET requsts.

    GET http://localhost:3000/artist/id/7

    { "a": 1, "b":2, "__jsonp_methods:["foo"] }

    var someFancyObject = { ...  };

    someFancyObject.foo = function( ) { ... };

    var ret = someFancyObject.foo({ meh => 1 },{ callback => function() { ... }} );

    POST http://localhost:8000/artist/id/7?jsonp=foo&jsonp_callback=gotData

COPYRIGHT AND LICENCE

Copyright (C) 2014 Tomasz Czepiel

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.10.1 or, at your option, any later version of Perl 5 you may have available.

cpanm Hyle

perl -MCPAN -e shell
install Hyle