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.