Socialwg/Social API/Twitter API

This is an analysis of the Twitter REST API to determine some of the key functionality in the API.

The main Twitter REST API documentation is at https://dev.twitter.com/rest/public. Each of the endpoints listed below has a page with more details there.

Overview

Twitter users can create one-way relationships ("follow") to other accounts. They can post short messages called "tweets", which are delivered to the home timeline of all their followers.

The Twitter REST API uses OAuth 1.0a for authentication. Older versions of the API supported HTTP Basic authentication.

This API has 101 endpoints listed below.

Twitter clients may only call REST API endpoints so many times per 15-minute interval for a single user. See https://dev.twitter.com/rest/public/rate-limiting for more information.

Entities

Entities in the Twitter API are encoded with JSON. Older versions supported RSS, Atom, and XML representations.

The main entities in the Twitter API are:

user: An account holder -- a person or a brand. See https://dev.twitter.com/overview/api/users
tweet: A single status update, with up to 140 characters of text, possibly with attached media. See https://dev.twitter.com/overview/api/tweets
direct message ("DM"): A single one-to-one message.
place: Use for geolocation of tweets. See https://dev.twitter.com/overview/api/places

Entities in the Twitter API are grouped into collections which are sorted in reverse chronological order. Special parameters are used to scroll through the collections.

Some endpoints only return the IDs of entities, which clients can retrieve from cache or resolve via batch lookup endpoints.

API endpoints

These are the API endpoints clustered by functionality.

Tweets

POST statuses/update
POST statuses/update_with_media
GET statuses/show/<id>
POST statuses/destroy/<id>: Create (with or without media), read, and delete a single "tweet", respectively. Tweets are immutable and can't be updated.

GET statuses/oembed: Get a single status in OEmbed format.

GET statuses/lookup: Get a batch of statuses by ID in a single API request.

Retweets

GET statuses/retweets/<id>
POST statuses/retweet/<id>: Get the "retweets" (shares, reposts) of a tweet, and retweet a tweet directly.

GET statuses/retweeters/ids: Get the IDs of the users who have retweeted this tweet.

Outbox

GET statuses/user_timeline: Collection of all tweets created by the user.

GET statuses/retweets_of_me: Collection of tweets that have been retweeted by others.

Inbox

GET statuses/home_timeline: Collection of tweets by people the user follows.

GET statuses/mentions_timeline: Collection of tweets that "mention" the user (with @nickname syntax).

Direct messages

POST direct_messages/new
GET direct_messages/show
POST direct_messages/destroy: Create, read, and delete a direct message. Direct messages are immutable.

GET direct_messages
GET direct_messages/sent: Inbox and outbox of direct messages

Social graph

POST friendships/create
GET friendships/show
POST friendships/update
POST friendships/destroy: CRUD for following other users.

GET friends/list
GET friends/ids: Get the accounts a user is following, either full user objects or just IDs
GET followers/list
GET followers/ids: Get the accounts that follow a user, either full user objects or just IDs

GET friendships/incoming
GET friendships/outgoing: For private accounts, which require user confirmation for following, these are incoming and outgoing queue of friendship requests.

GET friendships/lookup: Get a batch of friendships by ID.

Account management

GET account/verify_credentials: NOOP API endpoint to verify that OAuth credentials are correct.

GET account/settings
POST account/settings
POST account/update_delivery_device: Settings for the user.

POST account/update_profile
POST account/update_profile_background_image
POST account/update_profile_colors
POST account/update_profile_image
POST account/remove_profile_banner
POST account/update_profile_banner
GET users/profile_banner: Profile information visible to other users, including minor design elements of profile page.

GET users/contributees
GET users/contributors: Some accounts can be posted to by multiple authenticated users. These endpoints show which are available.

Blocking and muting

POST blocks/create
GET blocks/list
GET blocks/ids
POST blocks/destroy: Create, read and delete of "blocks". Blocked users cannot interact with the user directly (follow, mention, direct message).

POST mutes/users/create
GET mutes/users/ids
GET mutes/users/list
POST mutes/users/destroy: Create, read and delete of "mutes". Muted users' tweets aren't delivered to the user's home timeline, even if there is a follow relationship.

GET friendships/no_retweets/ids: Get IDs of users the user does not want to receive retweets from.

Content search

GET search/tweets: Search tweets globally by content.

POST saved_searches/create
GET saved_searches/list
GET saved_searches/show/<id>
POST saved_searches/destroy/<id>: Create, read, and delete "saved searches".

Users

GET users/lookup: Given a batch of IDs, return full user objects.

GET users/show: Return full user object for specified user.

GET users/search: Search for users by nickname, full name, location, or other profile data.

Social graph suggestions

GET users/suggestions/<slug>
GET users/suggestions
GET users/suggestions/<slug>/members: Get suggested users to follow. Twitter's algorithm does the suggesting.

Favorites

POST favorites/create
GET favorites/list
POST favorites/destroy: Create, read and destroy "favorites".

Contact lists

POST lists/create
GET lists/list
GET lists/show
POST lists/update
POST lists/destroy: Create, read, update and delete contact lists.

POST lists/members/destroy
GET lists/memberships
POST lists/members/create_all
GET lists/members/show
GET lists/members
POST lists/members/create
POST lists/members/destroy_all: Manage the members of a list.

GET lists/subscribers
POST lists/subscribers/create
GET lists/subscribers/show
POST lists/subscribers/destroy
GET lists/subscriptions: Manage the subscribers of a list. Other users can subscribe to a different user's list.

GET lists/ownerships
GET lists/statuses

Geocoding

POST geo/place
GET geo/id/<place_id>: Create and read places.

GET geo/similar_places
GET geo/reverse_geocode
GET geo/search: Search for places.

Trends

GET trends/place
GET trends/available
GET trends/closest

Service

GET application/rate_limit_status
GET help/configuration
GET help/languages
GET help/privacy
GET help/tos: Service-wide information.

Spam

POST users/report_spam: Users can report other tweets as spam.

Content

Special symbols

Content of tweets is parsed by the server, and some special symbols are handled in a particular way. It's not possible to opt out of this special handling.

URLS: URLs are shortened using the http://t.co/ URL shortener. Spam, viruses and other hazardous sites can be filtered out by the shortener.

@-mentions: Tweets that match "@<nickname>" will have the <nickname> part turned into a link to http://twitter.com/<nickname>. The user with that nickname will get the tweet in their "mentions" timeline. Mentions at the beginning of a tweet like "@<nickname> foo bar baz" will not be delivered to the authors' followers if they do not also follow the user with <nickname>.

hashtags: Tweets that match "#<hashtag>" will have the <hashtag> part replaced by a link to https://twitter.com/hashtag/<hashtag>.

Twitter cards

If an URL in a tweet has an HTML representation, and that representation has Twitter-specific <meta> tags in the <head>, Twitter will render the tweet as a Twitter card. Twitter cards can show images, video, audio, or provide download links for mobile apps.

Streaming

Twitter also has a streaming API. Clients do an HTTP-based long poll of a stream to get real-time updates.

Example JSON

Below is a (truncated) example JSON representation of a tweet object.

{
  "created_at": "Mon Aug 24 15:04:38 +0000 2015",
  "id": 635830076333027300,
  "id_str": "635830076333027328",
  "text": "This is kind of amazing, we have Homebrew Website Club meetups in 6 cities this week! http://t.co/yoq5Rmhn6i",
  "source": "<a href=\"http://aaronparecki.com\" rel=\"nofollow\">aaronparecki.com</a>",
  "truncated": false,
  "in_reply_to_status_id": null,
  "in_reply_to_status_id_str": null,
  "in_reply_to_user_id": null,
  "in_reply_to_user_id_str": null,
  "in_reply_to_screen_name": null,
  "user":  {
    "id": 14447132,
    "id_str": "14447132",
    "name": "Aaron Parecki",
    "screen_name": "aaronpk",
    "location": "Portland, OR",
    "description": "CTO @EsriPDX R&D Center • Cofounder of #indieweb/@indiewebcamp • Maintains http://t.co/zBgRc3GHvO • Creator of http://t.co/yDBCPnanjA",
    "url": "http://t.co/lhD9z0nimw",
    "entities":  {...},
    "created_at": "Sat Apr 19 22:38:15 +0000 2008",
    "utc_offset": -25200,
    "time_zone": "Pacific Time (US & Canada)",
    "profile_image_url": "http://pbs.twimg.com/profile_images/3657148842/934fb225b84b8fd3effe5ab95bb18005_normal.jpeg",
    ...
  },
  "geo": null,
  "coordinates": null,
  "place":  {...},
  "retweet_count": 1,
  "favorite_count": 2,
  "entities":  {...},
  ...
}