NAME

WWW::BigDoor - provides a perl interface for BigDoor's REST API.

VERSION

This document describes BigDoor version 0.1.1

SYNOPSIS

    use WWW::BigDoor;

    my $client = new WWW::BigDoor( $APP_SECRET, $APP_KEY );

    $currency_type_list = $client->GET( 'currency_type' );
    my $currency_data = {
        pub_title            => 'Banknotes',
        pub_description      => 'an example of the Purchase currency type',
        end_user_title       => 'Coins',
        end_user_description => 'can only be purchased',
        currency_type_id     => $currency_type_list->[0],
        currency_type_title  => 'Purchase',
        exchange_rate        => 900.00,
        relative_weight      => 2,
    };
    my $currency = $client->POST( 'currency', {format => 'json'}, $currency_data );

    my $currency_id = $currency->[0]->{'id'};

    $currency_data->{'pub_title'} = 'Coins';

    $client->PUT( sprintf( 'currency/%s', $currency_id ), {format => 'json'}, $currency_data );

    $currency = $client->GET( sprintf( 'currency/%s', $currency_id ), {format => 'json'} );

    $client->DELETE( sprintf( 'currency/%s', $currency_id ) );

  

DESCRIPTION

This module provides simple interface to BigDoor REST API with calls implmenting HTTP methods. For object-oriented interface see WWW::BigDoor::Resource.

For BigDoor API description consult documentation at http://publisher.bigdoor.com/docs/definitions

INTERFACE

new( $app_secret, $app_key, [$api_host] )

Constructs a new BigDoor API client object.

app_secret

The API secret supplied by BigDoor. (see API Keys http://publisher.bigdoor.com/)

app_key

The API key supplied by BigDoor. (see API Keys http://publisher.bigdoor.com/)

api_host

An alternative host to enable use with testing servers.

GET( $end_point, $params )

Sends a GET request to the API and returns a hash/array reference as returned from decode_json from JSON module.

end_point

The relative URI that comes directly after your API key in the BigDoor documentation.

params

The parameters to be sent via the GET query string.

PUT( $end_point, $params, $payload )

Sends a PUT request to the API and returns a hash/array reference as returned from decode_json from JSON module.

end_point

The relative URI that comes directly after your API key in the BigDoor documentation.

params

The parameters to be sent via the PUT query string.

payload

The parameters to be sent via the PUT request body.

POST( $end_point, $params, $payload )

Sends a POST request to the API and returns a hash/array reference as returned from decode_json from JSON module.

end_point

The relative URI that comes directly after your API key in the BigDoor documentation.

params

The parameters to be sent via the PUT query string.

payload

The parameters to be sent via the PUT request body.

DELETE( $end_point, $params )

Sends a DELETE request to the API and returns nothing.

do_request( $method, $end_point, $params, $payload )

Sends a request to the API, signing it before it is sent. Returns ?

method

HTTP method of request, can be one of GET, PUT, POST, DELETE.

end_point

The relative URI that comes directly after your API key in the BigDoor documentation.

params

The parameters to be sent via the query string.

payload

The parameters to be sent via the PUT or POST request body.

generate_signature( $url, $params, $payload )

Generates the appropriate signature given a url and optional params.

url

The full URL, including the base /api/publisher/[app_key].

params

The parameters to be sent via the query string.

payload

The parameters to be sent via the PUT or POST request body.

generate_token()

Generate UUID4 token

Accessors/Mutators generated with Class::Accessor

[get|set]_app_secret()

Get/Set secret for BigDoor API.

[get|set]_app_key()

Get/Set secret for BigDoor API.

[get|set]_api_host()

Get/Set hostname for server providing BigDoor API.

[get|set]_base_url()

Get/Set base URL for API (default is /api/published/[$app_key])

get_request_result()

Gets request result returned by underlying REST::Client request() call

get_response_code()

Gets HTTP response code for request.

get_response_content()

Gets undecoded response body content.

DIAGNOSTICS

Module doesn't produce any error or warning messages on its own.

In case of HTTP errors check HTTP response code returned by get_response_code() or response body returned by get_response_content().

For debugging purpose there is result object returned by REST::Client c<request()> call which could be accessed through get_request() and this result object contains HTTP::Response object.

CONFIGURATION AND ENVIRONMENT

WWW::BigDoor requires no configuration files or environment variables.

DEPENDENCIES

The module requires the following modules:

• REST::Client

• JSON

• URI

• Digest::SHA

• UUID::Tiny

Test suite requires additional modules:

• Test::Most

• Test::MockObject

• Test::MockModule

• Test::NoWarnings

• Hook::LexWrap

DIFFERENCES FROM PYTHON BIGDOORKIT

Method names get/put/post/delete were converted to upper case to avoid conflict with get() method inherited from Class::Accessor and for consinstence with LWP.

INCOMPATIBILITIES

None reported.

BUGS AND LIMITATIONS

Code is not fully covered by tests and there are not much tests for failures and, as consequence, not much parameters validation or checking for error conditions. Don't expect too much diagnosticts in case of errors.

No bugs have been reported.

Please report any bugs or feature requests to bug-bigdoor@rt.cpan.org, or through the web interface at http://rt.cpan.org.

TODO

• Implement parameters checking

• Improve test coverage

SEE ALSO

WWW::BigDoor::Resource for object-oriented interface.

AUTHOR

Alex L. Demidov <alexeydemidov@gmail.com>

LICENCE AND COPYRIGHT

BigDoor Open License Copyright (c) 2010 BigDoor Media, Inc.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

- This copyright notice and all listed conditions and disclaimers shall be included in all copies and portions of the Software including any redistributions in binary form.

- The Software connects with the BigDoor API (api.bigdoor.com) and all uses, copies, modifications, derivative works, mergers, publications, distributions, sublicenses and sales shall also connect to the BigDoor API and shall not be used to connect with any API, software or service that competes with BigDoor's API, software and services.

- Except as contained in this notice, this license does not grant you rights to use BigDoor Media, Inc. or any contributors' name, logo, or trademarks.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

cpanm WWW::BigDoor

perl -MCPAN -e shell
install WWW::BigDoor