Social Graph API: Legacy data format will be eliminated 1/11/2010

[Wilhelm Bierbaum]

We noticed that some clients are still calling social graph methods

without cursor parameters. We wanted to take time to make sure that

people were calling the updated methods which return data with cursors

instead of the old formats that do not.

As previously announced in September (http://bit.ly/46x1iL) and

November (http://bit.ly/3UQ0LU), the legacy data formats returned

as a result of calling social graph endpoints without a cursor 

parameter are deprecated and will be removed.

These formats have been removed from the API wiki since September.

You should always pass a cursor parameter. Starting soon, if you fail 

to pass a cursor, the data returned will be that of the first cursor

(-1) and the next_cursor and previous_cursor elements will be included.

If you aren't seeing next_cursor and previous_cursor in your results,

you are getting data back in the old format. You will need to adjust

your parser to handle the new format.

We're going to start assuming you want data in the new format

(users_list / users / user or id_list / ids / id) instead of the old

format (users / user or ids / id) regardless of your passing a cursor

parameter as of 1/11/2010.

* The old formats will no longer be returned after 1/11/2010. 

* Start using the new formats now by passing the 'cursor' parameter.

To recap, the old endpoints at

   /statuses/friends.xml

   /statuses/followers.xml

returned

    <users type="array">

      <user>

      <!-- ... omitted ... -->

      </user>

    </users>

or JSON like [{/*user record*/ /*, .../]

whereas

        /statuses/friends.xml?cursor=n

        /statuses/followers.xml?cursor=n

return data that looks like

    <users_list>

      <users type="array">

          <user>

          <!-- ... omitted ... -->

          </user>

      </users>

      <next_cursor>7128872798413429387</next_cursor>

      <previous_cursor>0</previous_cursor>

    </users_list>

or, the JSON equivalent:

    {"users":[{/*user record*/} /*, ...*/], "next_cursor":0, "previous_cursor":0}

and the old endpoints at 

    /friends/ids.xml

    /followers/ids.xml

returned data that looks like

    <ids>

      <id>1</id>

      <id>2</id>

      <id>3</id>

    </ids>

whereas

    /friends/ids.xml?cursor=n

    /followers/ids.xml?cursor=n

return data that looks like

    <id_list>

      <ids>

        <id>1</id>

        <id>2</id>

        <id>3</id>

      </ids>

      <next_cursor>1288724293877798413</next_cursor>

      <previous_cursor>-1300794057949944903</previous_cursor>

    </id_list>

    

or, the JSON equivalent:

    {"ids":[1, 2, 3], "next_cursor":0, "previous_cursor":0}

If you have any questions or comments, please feel free to post them

to twitter-development-talk. 

Thanks!

--

Wilhelm Bierbaum

Twitter Platform Team