Some changes and updates to the API and Tweet Button

[Matt Harris]

Hey everyone,

We've been working on a few fixes and optimisations which are making their way into the API.

The quick list (more information further down the email):

* [Now] Tweet Button share flow has some UI improvements and now supports mobile smart phones.

* [Now] Attempting to view a direct message which you did not send or receive now returns a HTTP status code of 403 instead of a 401

* [Now] Attempting to view or destroy a direct message without providing a message ID now returns a 400 status code instead of a 404

* [Now] We've added a new method /1/friendships/no_retweet_ids.{format} to let streaming clients know whose retweets to silence in timelines.

* [Now] An alternative set of URLs have been created for lists to allow requests by user_id or screen_name.

* [Soon] The trends endpoints on search.twitter.com are being turned off as they exist on api.twitter.com instead

* [Soon] followers/ids and friends/ids is being updated to set the cursor to -1 if it isn't supplied during the request. This changes the default response format.

More information:

[Now] Tweet Button share flow has had some UI improvements which includes support for mobile smart phones.

----------------

This change is automatic and all users of the Tweet Button will already be receiving the new design. When a smartphone is detected, we render the mobile view for you - meaning you don't need to do anything to have your Tweet Button support mobile users.

[Now] Attempting to view a direct message which you did not send/receive now returns 403 instead of 401

----------------

This change affects /1/direct_messages/show.{format}. If the current_user is not the sender or receiver of the message, we now return a 403 (instead of a 401) with the message "You may only view direct messages you've sent or received."

[Now] Attempting to destroy a direct message without providing a message ID now returns a 400 instead of a 404

----------------

This change affects /1/direct_messages/show.{format} and /1/direct_messages/destroy.{format}. If the id parameter is not provided, we now return a 400 (instead of a 404) with the error message "Missing required parameter: ID."

[Now] We've added a new method /1/friendships/no_retweet_ids.{format} to help streaming clients know whose retweets to silence in timelines.

----------------

Userstreams and Sitestreams include all retweets created by a users followings. The new REST API method /1/friendships/no_retweet_ids.{format} provides developers of Streaming applications with a comma separated list of user_ids for which the authenticating user has said they do not want to receive retweets from.

[Now] An alternative set of URLs have been created for lists to allow requests by user_id or screen_name.

----------------

Instead of providing a users screen_name in the URL for a list, you can now choose to provide either their user_id or screen_name. The old routes will continue to operate but we encourage developers to transition to the new routes as soon as possible.

The new routes and parameter names are:

POST /1/lists/create -- name, mode, description

POST /1/lists/update -- [list identifier], mode, description

GET /1/lists -- user_id, screen_name, cursor

GET /1/lists/show -- [list identifier]

POST /1/lists/destroy -- [list identifier]

GET /1/lists/statuses -- [list identifier], since_id, max_id

GET /1/lists/memberships -- [list identifier], cursor, member_user_id, member_screen_name

GET /1/lists/subscriptions -- [list identifier], cursor, subscriber_user_id, subscriber_screen_name

GET /1/lists/members -- [list identifier], cursor

POST /1/lists/members/create -- [list identifier], member_user_id, member_screen_name

POST /1/lists/members/create_all -- [list identifier], member_user_ids, member_screen_names

POST /1/lists/members/destroy -- [list identifier], member_user_id, member_screen_name

GET /1/lists/members/show -- [list identifier], member_user_id, member_screen_name

GET /1/lists/subscribers -- [list identifier], cursor

POST /1/lists/subscribers/create -- [list identifier]

POST /1/lists/subscribers/destroy -- [list identifier]

GET /1/lists/subscribers/show -- [list identifier], subscriber_user_id, subscriber_screen_name

[list identifier] represents a combination of:

  screen_name or user_id 

and

  slug or list_id

  

If cursor is not provided it will default to -1.

[Soon] The trends endpoints on search.twitter.com are being turned off as they exist on api.twitter.com instead

----------------

The trends API used to be hosted on search.twitter.com but was moved last year to api.twitter.com. If you haven't transitioned your trends requests to api.twitter.com yet you should make the change now. In the next couple of weeks the trends API will stop being served from search.twitter.com.

[Soon] followers/ids and friends/ids is being updated to set the cursor to -1 if it isn't supplied during the request. This changes the default response format

----------------

For those of you who already use cursor=-1 in your requests, this won't make any difference to your queries and they will still work as before. Those who do not add cursor=-1 to their requests should know the response format will change.

For XML paged responses the difference is that the ids element you previously received is now contained within an id_list element. There are also two cursor elements which allow you to page back and forth through the list.

<?xml version="1.0" encoding="UTF-8"?>

<id_list>

  <ids>

  <id>143206502</id>

  <id>143201767</id>

  <id>777925</id>

</ids>

<next_cursor>0</next_cursor><previous_cursor>0</previous_cursor>

</id_list>

For JSON paged responses the difference is that the array of ids you previously received are now contained within an object, referenced by the "ids" key. There are string and integer representations of the next and previous cursors.

{

  "previous_cursor": 0,

  "ids": [

143206502,

143201767,

777925

  ],

  "previous_cursor_str": "0",

  "next_cursor": 0,

  "next_cursor_str": "0"

}

As ever, if you have any questions about this let us know on the list or through @twitterapi.

@themattharris

Developer Advocate, Twitter

http://twitter.com/themattharris