NAME

WebService::Etsy - Access the Etsy REST API.

SYNOPSIS

    my $api = WebService::Etsy->new( api_key => 'key' );

    # Call API methods as object methods
    my $resp = $api->getUsersByName( search_name => 'test' );
    die $api->last_error if ( ! defined $resp );

    # Returns a Response object which has methods
    print "Found: " . $resp->count . " users\n";
    print "Have: " . scalar @{ $resp->results } . " results\n";

    # But also behaves like an arrayref of Resource objects
    for ( @$resp ) {
        # Resources are objects, like WebService::Etsy::Resource::User
        print $_->user_name, "\n";
    }

    $resp = $api->getUserDetails( user_id => 'testuser' );
    # As a convenience, you can call Resource object methods
    # on the Response object, which will be called on the first
    # Resource object so
    print $resp->user_name, "\n";
    # is the same as
    print $resp->[ 0 ]->user_name, "\n";

DESCRIPTION

Note: this module is alpha code - a fairly functional proof of concept. In addition, this 0.7 release is a quick hack to make something that works with the v2 API since the v1 API is being taken offline. It doesn't support the "private" API, only the "public" (no OAuth) API, and then only a subset that matches roughly with what the v1 API provided. The v2 API's method names aren't backwards-compatible with the v1 API so some re-writing will be necessary.

This module accesses the Etsy API, as described at http://developer.etsy.com/.

The API is RESTful, and returns JSON. This module abstracts this away to present a standard Perl object interface.

The API methods are generated from details returned by the getMethodsTable API method. A pre-built package containing the methods is shipped with this distribution, but you can re-build it using the "generate_methods.pl" script that is distributed with this code:

   perl generate_methods.pl api_key > Methods.pm

Methods.pm should then replace the existing WebService::Etsy::Methods file in your Perl library.

Currently the data is provided just as it comes back from the Etsy API. Future development will include caching, automatic retrieval of larger data sets, cross-object references, etc.

Calls to the API methods of the WebService::Etsy object will return a WebService::Etsy::Response object. See that object's documentation on the methods available.

The Response object contains an arrayref of WebService::Etsy::Resource objects, which implement interfaces to match the documentation at http://developer.etsy.com/docs/read/resources. See the WebService::Etsy::Resource page for documentation on specific methods.

METHODS

new( %opts )

Create a new API object. Takes a hash of options which can include ua, api_key, use_sandbox, base_uri, log_file, default_limit, and default_detail_level, which correspond to setting the values of the relevant methods (described below).

api_key( $key )

Get/set the API key to use for API requests.

use_sandbox( $bool )

Boolean toggle controlling whether to access the sandbox version of the API or not.

base_uri( $uri )

Get/set the base URI for requests. Defaults to "http://beta-api.etsy.com/v1".

ua( $agent )

Get/set the user agent object that will be used to access the API server. The agent should be an object that implements the same interface as LWP::UserAgent.

By default, it's an LWP::UserAgent with the agent string "WebService::Etsy".

default_limit( $limit )

Get/set the default limit parameter for a request for those methods that accept a limit parameter. Takes an integer 1-50. Default is 10.

default_detail_level( $level )

Get/set the default detail level to request for those methods that accept such a parameter. Takes one of "low", "medium", or "high". Default is "low".

last_error

Returns the message from the last error encountered.

log_file

Get/set the name of the log file to use.

log( $message )

Write $message to the log.

API METHODS

API methods take a hash of parameters. In the event of an error, they will return undef, and the error message can be retrieved using the last_error() method.

    my $resp = $api->getUserDetails( user_id => 'testuser', detail_level => 'high' );

See http://developer.etsy.com/docs#commands for more details on the methods and parameters.

Any API method will also accept ua, base_uri, or api_key arguments which will override those configured in the API object.

SEE ALSO

http://www.etsy.com/storque/etsy-news/tech-updates-handmade-code-etsys-beta-api-3055/, http://developer.etsy.com/, WebService::Etsy::Response, WebService::Etsy::Resource.

AUTHOR

Ian Malpass (ian-cpan@indecorous.com)

COPYRIGHT

Copyright 2009, Ian Malpass

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