The Twitter API has REST APIs and Streaming APIs, which allow developers to access core data such as timelines, status data, user information, and so on.
Twitter uses three-legged OAuth to make requests.
Note
Important aspects of OAuth with Twitter API
The client application doesn't need to store a login ID and password. The application sends an access token representing the user with each request instead of using user credentials.
The POST
variables, query parameters, and the URL of the request always remain intact for a request to successfully complete.
The user decides what applications can act on his behalf and can remove authorization at any time.
A unique identifier for each request (the oauth_nonce
identifier) prevents replaying the same request again in case it gets snooped.
To send requests to Twitter, most developers may find the initial setup a bit confusing. The article at https://blog.twitter.com/2011/improved-oauth-10a-experience shows how to create an application, generate the keys, and generate a request using the OAuth tool.
Here is an example of a request generated by the OAuth tool in Twitter, showing a query to get statuses for the twitterapi
handle:
Note
The Twitter API does not support unauthenticated requests and has very strict rate-limiting policies.
curl --get 'https://api.twitter.com/1.1/statuses/user_timeline.json' --data 'screen_name=twitterapi' --header 'Authorization: OAuth oauth_consumer_key="w2444553d23cWKnuxrlvnsjWWQ", oauth_nonce="dhg2222324b268a887cdd900009ge4a7346", oauth_signature="Dqwe2jru1NWgdFIKm9cOvQhghmdP4c%3D", oauth_signature_method="HMAC-SHA1", oauth_timestamp="1404519549", oauth_token="456356j901-A880LMupyw4iCnVAm24t33HmnuGOCuNzABhg5QJ3SN8Y", oauth_version="1.0"'—verbose.
This gives an output as shown:
GET /1.1/statuses/user_timeline.json?screen_name=twitterapi HTTP/1.1 Host: api.twitter.com Accept: */* HTTP/1.1 200 OK … "url":"http:\/\/t.co\/78pYTvWfJd","entities":{"url":{"urls":[{"url":"http:\/\/t.co\/78pYTvWfJd","expanded_url":"http:\/\/dev.twitter.com","display_url":"dev.twitter.com","indices":[0,22]}]},"description":{"urls":[]}},"protected":false,"followers_count":2224114,"friends_count":48,"listed_count":12772,"created_at":"Wed May 23 06:01:13 +0000 2007","favourites_count":26,"utc_offset":-25200,"time_zone":"Pacific Time (US & Canada)","geo_enabled":true,"verified":true,"statuses_count":3511,"lang":"en","contributors_enabled":false,"is_translator":false,"is_translation_enabled":false,"profile_background_color":"C0DEED","profile_background_image_url":"http:\/\/pbs.twimg.com\/profile_background_images\/656927849\/miyt9dpjz77sc0w3d4vj….
The following table summarizes the commonly used verbs in the Twitter REST API:
Verb |
Description |
---|---|
|
This is used to retrieve resources such as users, followers, favorites, subscribers, and so on. |
|
This is used to create resources such as users, followers, favorites, subscribers, and so on. |
|
This is used to replace resources. For example, to update the friendships, the URL will be |
|
This is used to delete resources such as deleting direct messages, unfollowing someone, and so on. For example, the URL will be |
The current version for the Twitter API is 1.1. It only supports JSON and no longer supports XML, RSS, or Atom. With the Twitter API Version 1.1, all clients need to be authenticated using OAuth to make queries. The Twitter API Version 1.0 has been deprecated and there is a 6-month window to move to the new version.
The Twitter API returns standard HTTP error codes in the responses to the REST API. It returns 200 OK
in case of success. It returns 304 Not Modified
when there is no data to return, 401 Not Authorized
in case authentication credentials were missing or incorrect, 500 Internal Server Error
when something is broken and needs to be posted to the forum, and so on. Along with detailed error messages, the Twitter API produces machine-readable error codes. For example, an error code 32
in the response implies the server could not authenticate the user. For more details, check https://dev.twitter.com/docs/error-codes-responses.