Net::Twitter::Role::API::Lists(3p)

NAME
Net::Twitter::Role::API::Lists - Twitter Lists API support for Net::Twitter

SYNOPSIS
  use Net::Twitter;

  my $nt = Net::Twitter->new(traits => ['API::Lists']);
  $nt->credentials($username, $password);

  my $list = $nt->create_list(
      $my_screen_name,
      { name => 'My List Name', mode => private }
  );

  my $r = $nt->add_list_member(
      $my_screen_name,
      $list->{slug},
      { id => $member_user_id }
  );

DESCRIPTION
This module add support to Net::Twitter for the Twitter Lists API.

The module is experimental and the method names, parameters, and implementation may change without notice. The Twitter Lists API itself is in beta ad the documentation is just a draft. When the Twitter Lists API specification is stable, expect a stable release of this module.

METHODS
Currently, the API::Lists methods can be called with positional parameters for the parameters used to compose the URI path. Additional parameters, including both required and optional parameters are passed in a HASH reference as the final argument to the API. All parameters may be passed in the HASH ref, if preferred.

Many of the methods take a "slug" parameter. The "slug" is a URI safe identifier assigned by Twitter for each list, based on the list's name. A "slug" is unique to a user, but is not globally unique. To identify a specific list, both the "user" and "slug" parameters are required.

Twitter has already announced upcoming changes to the Lists API. Code written now will require modification when the API is finalized. You have been warned.

<http://groups.google.com/group/twitter-api-announce/browse_thread/thread/1eefb0263ea73ac8>

new The following arguments are available to new (in addition to those documented in Net::Twitter).

    lists_api_url
        The base URL for the Twitter Lists API. Defaults to "http://twitter.com"

create_list
    Parameters: user, name, mode Required: user, name

    Creates a new list for the authenticated user. The "mode" parameter may be either "public" or "private". If not specified, it defaults to "public".

update_list
    Parameters: user, slug, name, mode

    Updates a list to change the name, mode, or both.

list_lists
    Parameters: user

    Returns the lists for the specified user. If the user is the authenticated user, it returns both public and private lists. Otherwise, it only returns the public lists.

list_memberships
    Parameters: $user

    Returns a the lists for which the specified user is a member.

delete_list
    Parameters: user, slug

    Deletes a list.

list_statuses
    Parameters: user, slug, [ next_cursor | previous_cursor ]

    Returns the statuses for list members. The optional cursor parameters provide paging.

get_list
    Parameters: user, slug

    Returns the specified list.

add_list_member
    Parameters: user, slug, id

    Adds the user identified by "id" to the specified list.

list_members
    Parameters: user, slug, [ id ]

    Returns the members of the specified list. Use the optional "id" parameter to check the list to see if user "id" is a member.

remove_list_member
    Parameters: user, slug, id

    Removes the member with "id" from the specified list.

subscribe_list
    Parameters: user, slug

    Subscribes the authenticated user to the specified list.

list_subscribers
    Parameters: user, slug

    Returns the subscribers to the specified list.

unsubscribe_list
    Parameters: user, slug

    Unsubscribes the authenticated user from the specified list.

is_subscribed_list
    Parameters: user, slug, id

    Check to see if the user identified by "id" is subscribed to the specified list.

SEE ALSO
Net::Twitter

AUTHOR
Marc Mims <marc@questright.com>

COPYRIGHT
Copyright (c) 2009 Marc Mims

LICENSE
This library is free software. You may redistribute and modify it under the same terms as Perl itself.