Draft of List API documentation

43 views
Skip to first unread message

Marcel Molina

unread,
Oct 16, 2009, 3:04:29 AM10/16/09
to twitter-deve...@googlegroups.com, twitter-ap...@googlegroups.com
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 &amp; 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 &amp; 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

Reply all
Reply to author
Forward
0 new messages