Hey folks. As some of you have likely read we're starting to do some
private beta testing of our new lists feature. We're not quite ready
to open it up to everyone but we've made some headway on the API and
wanted to share some details of what we've got so far.
There are a handful of things on our todo lists so don't consider this
signed and sealed just yet.
You may notice this API is a bit of a departure from the rest of the
API. It's a bit more, errr, REST than the rest.
First off, here's the current payload for a list:
<?xml version="1.0" encoding="UTF-8"?>
<list>
<id>1416</id>
<name>tall people</name>
<full_name>@noradio/tall-people</full_name>
<slug>tall-people</slug>
<subscriber_count>0</subscriber_count>
<member_count>3</member_count>
<uri>/noradio/tall-people</uri>
<mode>public</mode>
<user>
<id>3191321</id>
<name>Marcel Molina</name>
<screen_name>noradio</screen_name>
<location>San Francisco, CA</location>
<description>Engineer at Twitter on the @twitterapi team, obsessed
with rock climbing & running. In a past life I was a member of the
Rails Core team.</description>
<profile_image_url>http://a3.twimg.com/profile_images/53473799/marcel-euro-rails-conf_no...</profile_image_url>
<url>http://project.ioni.st</url>
<protected>false</protected>
<followers_count>40059</followers_count>
<profile_background_color>9AE4E8</profile_background_color>
<profile_text_color>333333</profile_text_color>
<profile_link_color>0084B4</profile_link_color>
<profile_sidebar_fill_color>DDFFCC</profile_sidebar_fill_color>
<profile_sidebar_border_color>BDDCAD</profile_sidebar_border_color>
<friends_count>354</friends_count>
<created_at>Mon Apr 02 07:47:28 +0000 2007</created_at>
<favourites_count>131</favourites_count>
<utc_offset>-28800</utc_offset>
<time_zone>Pacific Time (US & Canada)</time_zone>
<profile_background_image_url>http://a1.twimg.com/profile_background_images/18156348/jessica_tiled....</profile_background_image_url>
<profile_background_tile>true</profile_background_tile>
<statuses_count>3472</statuses_count>
<notifications>false</notifications>
<geo_enabled>true</geo_enabled>
<verified>false</verified>
<following>false</following>
</user>
</list>
=== Lists ===
POST '/:user/lists.:format'
Creates a new list for the authenticated user.
Parameters:
* name: the name of the list. (required)
* mode: whether your list is public of private. Values can be
'public' or 'private'. Public by default if not specified. (optional)
Usage notes:
":user" in the url should be the screen name of the user making the
request to create the list
Supported formats:
xml, json
e.g.
curl -u USERNAME:PASSWORD -d "name=tall people&mode=private"
http://twitter.com/noradio/lists.xml
POST/PUT '/:user/lists/:list_slug.:format'
Updates the specified list.
Takes the same parameters as the create resource at POST
'/:user/lists.:format' (:name and :mode).
Supported formats:
xml, json
e.g.
curl -u USERNAME:PASSWORD -d "name=giants&mode=public"
http://twitter.com/noradio/lists/tall-people.xml
GET '/:user/lists.:format'
Lists your lists.
Supported format:
xml, json
e.g.
curl -u USERNAME:PASSWORD http://twitter.com/noradio/lists.xml
GET '/:user/lists/memberships.:format'
List the lists the specified user has been added to.
Supported formats:
xml, json
e.g.
curl -u USERNAME:PASSWORD http://twitter.com/noradio/lists/memberships.xml
DELETE '/:user/lists/:list_slug.:format'
Delete the specified list owned by the authenticated user.
Parameters:
* list_slug: the slug of the list you want to delete. (required)
Supported formats:
xml, json
e.g.
curl -u USERNAME:PASSWORD -X DELETE
http://twitter.com/noradio/lists/tall-people.xml
GET '/:users/lists/:list_slug/statuses.:format'
Show tweet timeline for members of the specified list.
Parameters:
* list_slug: the slug of the list you want the member tweet timeline
of. (required)
* next/previous_cursor: used to "page" through results (optional)
Supported formats:
xml, json
e.g.
curl -u USERNAME:PASSWORD
http://twitter.com/noradio/lists/tall-people/statuses.xml
GET '/:users/lists/:list_slug.:format'
Show a specific list you can use the new resource.
Supported formats:
xml, json
e.g.
curl -u USERNAME:PASSWORD http://twitter.com/noradio/lists/tall-people.xml
=== List members ===
POST '/:user/:list_slug/members.:format'
Add a member to a list.
Parameters:
* id: the id of the user you want to add as a member to the list. (required)
Usage notes:
The :list_slug portion of the request path should be the slug of the
list you want to add a member to.
Supported formats:
xml, json
e.g.
curl -u USERNAME:PASSWORD -d "id=123456789"
http://http://twitter.com/noradio/tall-people/members.xml
GET '/:user/:list_slug/members.:format'
Members of the specified list.
Supported formats:
xml, json
e.g.
curl -u USERNAME:PASSWORD http://twitter.com/noradio/tall-people/members.xml
DELETE '/:user/:list_slug/members.:format'
Remove a member from the specified list.
Parameters:
* id: the id of the user you want to remove as a member from the
list. (required)
Usage notes:
The :list_id portion of the request path should be the slug of the
list you want to add a member to.
Supported formats:
xml, json
e.g.
curl -u USERNAME:PASSWORD -X DELETE -d "id=123456789"
http://twitter.com/noradio/tall-people/members.xml
GET '/:user/:list_slug/members/:id.:format'
Check if a user is a member of the specified list.
Usage notes:
The :id is the id of the user you're inquiring about.
Supported formats:
xml, json
e.g.
curl -u USERNAME:PASSWORD
http://twitter.com/noradio/tall-people/members/123456789.xml
=== List subscribers ===
POST '/:user/:list_slug/subscribers.:format'
Subscribe the authenticated user to the specified list.
Supported formats:
xml, json
e.g.
curl -u USERNAME:PASSWORD -X POST
http://twitter.com/noradio/tall-people/subscribers.xml
GET '/:user/:list_slug/subscribers.:format'
List the users subscribed to the specified list.
Supported formats:
xml, json
e.g.
curl -u USERNAME:PASSWORD
http://twitter.com/noradio/tall-people/subscribers.xml
DELETE '/:user/:list_slug/subscribers.:format'
Unsubscribe the authenticated user from the specified list.
Supported formats:
xml, json
e.g.
curl -u USERNAME:PASSWORD -X DELETE
http://twitter.com/noradio/tall-people/subscribers.xml
GET '/:user/:list_slug/subscribers/:id.:format'
Check if a user subscribes to the specified list.
Usage notes:
The :id is the id of the user you're inquiring about.
Supported formats:
xml, json
e.g.
curl -u USERNAME:PASSWORD
http://twitter.com/noradio/tall-people/subscribers/123456789.xml
More to come soon. Stay tuned!
--
Marcel Molina
Twitter Platform Team
http://twitter.com/noradio
|
