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_normal.jpg</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.jpg.jpeg</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