Updates to the List API (list descriptions, cursoring lists of lists, finding by list id rather than slug & more consistent names)

[Marcel Molina]

Two additions and two changes to the List API will be deployed in the
next few days:

* List descriptions
We're adding a description to every list. You'll be able to specify a
description when you create or update a list and the description will
be included in the payload.

* Cursoring through lists of lists
All resources that return a list of lists will include next and
previous cursors and will accept a :cursor parameter.

* Finding by list id rather than slug
When you change the name of a list, the slug will be updated to
reflect that change. That means using the slug in the url for
resources to operate on lists requires the onerous task of validating
that the slug for the list you are about to do something with hasn't
been updated since the last time you stored its slug. What a nightmare
:-)

Every list also has an id. This value won't change. We'll be changing
the API to replace all instances of a list slug in urls to be list ids
instead.

* Consistent names
The terminology we've used thus far for people you follow with a list
is members. The terminology for people who are following a list is
subscribers. We're going to mirror the terminology used for users and
change it to followers and following respectively.

So:

/:user/lists/:list_id/memberships becomes /:user/lists/:list_id/followers

/:user/lists/:list_id/subscribers becomes /:user/lists/:list_id/following

As we deploy these changes we'll send out a heads up on the dev list
and @twitterapi.

--
Marcel Molina
Twitter Platform Team
http://twitter.com/noradio

[Jesse Stay]

Maybe a little more appropriate to post this to a private list (no pun intended) for beta users?  I admit I feel a little jealous every time I see one of these updates, unless there's some way to get into the beta.

Thanks,

Jesse

[Tim Haines]

Marcel,

Great changes. A couple of questions:

- How long can a list description be?
- A title can only be 15 chars - will that remain unchanged?
- Will there be a little overlap where memberships and subscribers
will still work while people migrate to followers/following?

It would be awesome if there was a way to retrieve all member ids and
a separate call for subscriber ids - cursored if necessary.

Also, filed an edge case bug around list error messages a couple of
days ago.
http://code.google.com/p/twitter-api/issues/detail?id=1145&sort=-opened&colspec=ID%20Stars%20Type%20Status%20Priority%20Owner%20Summary%20Opened%20Modified%20Component

Cheers,

Tim.

[Michael Steuer]

+1

[Marcel Molina]

Answers inline:

On Wed, Oct 28, 2009 at 1:14 PM, Tim Haines <tmha...@gmail.com> wrote:
>
> Marcel,
>
> Great changes.  A couple of questions:
>
> - How long can a list description be?

160 :-)

> - A title can only be 15 chars - will that remain unchanged?

Unchanged.

> - Will there be a little overlap where memberships and subscribers
> will still work while people migrate to followers/following?

Yeah. There will be overlap for some period of time for those who
might need to transition.

> It would be awesome if there was a way to retrieve all member ids and
> a separate call for subscriber ids - cursored if necessary.

Right, I'll add that to the "list of things to consider" :-)

> Also, filed an edge case bug around list error messages a couple of
> days ago.
> http://code.google.com/p/twitter-api/issues/detail?id=1145&sort=-opened&colspec=ID%20Stars%20Type%20Status%20Priority%20Owner%20Summary%20Opened%20Modified%20Component

Thanks.

[Rich]

+1 to this

Any news on when the rest of us devs can get access to this to work on
our apps?

[Marcel Molina]

Real soon now. We appreciate everyone's patience while we gradually
ramp up traffic to lists to ensure we've got all our ducks in a row.

[Naveen]

How does one keep a list up to date for a client without the concept
of since_id, like we have for the timeline methods? I look at a lists
as just a different timeline (granted one filtered to specific users),
but that is how I would expect to view them in a client.

From my understanding of cursors, on each request we have to start at
-1 (to start paging) and page until we find an id that we already have
locally. While this will work, it has a high probability of always
over requesting data..

So if I have a list with two people in it, and they only tweet once a
week, when I poll for updates of this list (say every 30min) the data
is going to be the same most of the time(last 100 messages that these
two people post). This seems like a waste of bandwidth for Twitter and
us.. Some may argue that bandwidth is cheap, but it really is not on
mobile devices. Some carriers charge per kb, but even on unlimited
plans every byte transferred translates to additional battery drain..

Is there some concept of the cursor that I am not understanding that
will allow us to also filter based on something like since_id? So we
want to get messages newer than we already have and notify the user
that the list has something new to display.

Thanks to anyone who can clarify if I am misunderstanding something.

--Naveen

[Marcel Molina]

The cursors are for lists of lists and lists of users followed
by/following lists. The statuses timeline for a given list takes all
the same options you'd expect to manage status timelines.

[Naveen Ayyagari]

Thanks for the quick response. I guess I was confused.

[Jeremy Felt]

It appears that user/lists.xml only shows lists that are created by
the user and not those that they follow.

Any change coming to that or am I missing a way to see all lists that
a user follows?

Thanks,
Jeremy

[Dan]

The update says all requests that produce a list *of lists* will have
a cursor option.

What about lists of members following/followed on/by a list?

If I want to download the list of people following a list, members.xml
currently gives only 20 users. Is there a way to ask for more, or to
get the next page?

[David Neubauer]

Has any figured out how to get a the lists I'm subscribed to. I didn't
realize how much I'd want this part of it. Please say it's coming...

[Naveen Ayyagari]

+1
Is there no way to view the lists that a user is subscribed to? As a
client, it seems kind of silly that we can't allow the user to view a
list that they already subscribe to with out them having to go find
the list again. Kind of a big hole, because that means we will have to
cache a separate list of lists that user uses frequently and it wont
be the same as on Twitter website.

[Tim Haines]

Yes, members will return a next_cursor.  Send that value back as a cursor url param. 

[LeeS - @semel]

Does calling the status timeline for a list count against rate limit?

What I'm thinking of is doing an Ajax widget that auto updates with
new tweets from a list every few seconds,
similar to how many people use the Search API to do this by hashtag.

If the status API request is rate limited this would obviously not
work.

[Rich]

Well we be able to use slug or will we HAVE to use list id? At the
moment I'm using the slug in my API calls

[Rich]

Actually following on from this, I see @screenName/listName
automatically links to the list on the site, so surely we have to be
able to call the API using listNames too unless there is a reverse
lookup API to convert list id to slug?

[Dave Briccetti]

I wrote a method for it: getListNamed, which gets the list (and its
slug) by brute force.

http://github.com/dcbriccetti/talking-puffin/blob/master/twitter-api/src/main/scala/org/talkingpuffin/twitter/AuthenticatedSession.scala

[twittelator]

:user/lists/subscriptions.:format

gets the lists that the user has subscribed to.

Andrew Stone
Twitter / @twittelator
http://www.stone.com
got iPhone?
http://tinyurl.com/twitpro
http://tinyurl.com/intentionizer
http://tinyurl.com/gesture-buy
http://tinyurl.com/igraffiti
http://tinyurl.com/talkingpics
http://tinyurl.com/mobilemix
http://tinyurl.com/soundbite
http://tinyurl.com/icreated
http://tinyurl.com/pulsar-app


On Oct 30, 5:00 am, "David Neubauer" <davidneubauer.gro...@gmail.com>
wrote:

[Rich]

Can we get some form of confirmation on the list slug/id issue. At
the moment calling by ID doesn't work anyway so it's only using the
slug.

My preference would be to allow either (in a similar way to the other
REST api's where you can use user id or screenName)

On Oct 31, 10:04 pm, twittelator <and...@stone.com> wrote:
> :user/lists/subscriptions.:format
>
> gets the lists that the user has subscribed to.
>
> Andrew Stone

> Twitter / @twittelatorhttp://www.stone.com

[Marcel Molina]

Currently it's still slug. It hasn't been updated yet. When it is
updated it will for some period of transition accept a slug or an id
but eventually support for the slug in the url will be removed
entirely.

[kaiser...@gmail.com]

I have to second Rich on this - ID-only is flawed, as twitter supports hotlinking lists by name (@username/slug) in tweets, and links that to the list page. If clients want to offer the same behavior, this is not possible if the API only supports IDs (or would require a potentially large number of additional requests to get the user's lists and page through them to find the one mentioned).

Marco
------------------------

[Marcel Molina]

Resolving a @screen_name/list_name reference in a tweet is a
compelling argument for making the url parameter polymorphic and not
deprecating the use of slugs. I will cogitate.

[Rich]

Using ID only for me is fine, except in the case we mention. If there
was a REST api to find a list ID based on a slug then it would mean we
could still resolve @screen_name/list_name links otherwise we wouldn't
be able to replicate it, except by brute force which would use yet
more API calls.

On Nov 1, 6:14 pm, Marcel Molina <mar...@twitter.com> wrote:
> Resolving a @screen_name/list_name reference in a tweet is a
> compelling argument for making the url parameter polymorphic and not
> deprecating the use of slugs. I will cogitate.
>
>
>
>
>
> On Sun, Nov 1, 2009 at 10:09 AM,  <kaiser.ma...@gmail.com> wrote:
> > I have to second Rich on this - ID-only is flawed, as twitter supports hotlinking lists by name (@username/slug) in tweets, and links that to the list page. If clients want to offer the same behavior, this is not possible if the API only supports IDs (or would require a potentially large number of additional requests to get the user's lists and page through them to find the one mentioned).
>
> > Marco
> > ------------------------
>
> > -----Original Message-----
> > From: Marcel Molina <mar...@twitter.com>
> > Date: Sun, 1 Nov 2009 10:02:31
> > To: <twitter-deve...@googlegroups.com>
> > Subject: [twitter-dev] Re: Subscribed Lists
>
> > Currently it's still slug. It hasn't been updated yet. When it is
> > updated it will for some period of transition accept a slug or an id
> > but eventually support for the slug in the url will be removed
> > entirely.
>

[Marcel Molina]

There is, in a sense, an API for resolving a list id by passing in a
slug. It's the show resource for a list. You'll either get a 404
(which means the slug no longer exist) or you'll get the list payload
which will include the id.

[Rich]

Thanks for that Marcel, well if it's decided to completely abandon
slugs I'll have to go down that route.

Any idea on whether both call types will be allowed yet? Obviously
the main lookups will are quick to switch between, just this
@screen_name/list_name that'll take more work if we can't use the
slug.

[Marcel Molina]

Both will be allowed.

[Tim Haines]

Hey Marcel,

Just checking - You haven't rolled this change yet right?:

 /:user/lists/:list_id/memberships becomes /:user/lists/:list_id/followers

It seems attempting to follow a user who doesn't exist (through the members post) results in a 500 at the moment, rather than a 404.

Tim.