Help
An application programming interface, or API, is what allows an application with data to share it with the rest of the world. An API is like a no-frills website, accessed through URL requests but returning structured data instead of web pages displayed in a browser. The data returned is structured to make it easy to parse and get to the information inside. APIs also tend to separate all of the functionality of the site into single, specific actions, such as “get a list of tweets” or “change my profile picture.” By combining several kinds of requests, you can use an API to power your own custom applications.
The design of the Twitter API attempts to adhere to the principles of RESTful systems. Roy Fielding conceived of REpresentational State Transfer (REST) less than a decade ago: this approach increases the ease of development as well as the scalability and flexibility of applications by making sure the data is layered, stateless, and well defined. Switching from XML to JSON, for example, is a simple matter of changing the extension on the URL used to make the request; it isn’t necessary to reengineer the application or switch development platforms.
In this section, I’ll present you with some basic instructions on how to access the Twitter API, select from HTTP methods, authenticate your API requests, and manage imposed limits.
The Twitter API permits three kinds of HTTP requests: GET, POST, and DELETE. The default request is submitted with a GET, which passes parameters as an encoded URL query string. For API methods that change things—for example, updating or deleting status information, direct messages, or associations in the follow network—a POST is needed.
Note
Where indicated in the API methods, the id parameter is sent as part of the URL (substitute this parameter
with either a user ID or a username). No form data is needed for any
of these methods.
The GET method accepts a URL and uses it to retrieve something from another server, after any necessary processing is done. If the URL is an index.php web page, for example, the GET method will capture the HTML generated by the PHP, not the PHP code itself.
Header information passed to the GET method can change its
behavior. In particular, GET looks at the If-Modified-Since field and captures the
output only if doing so fulfills that header
condition. The purpose of this constraint is to reduce redundant
network activity by avoiding unnecessary data transfers.
The following Twitter API methods are accessed with a GET:
Note
Most of the methods in the API can be requested using GET.
This means your parameters can be passed as a URL query string, or a
series of name/value pairs following a ?.
This is great for testing, as all you need to do is type the request URL into the location bar in a regular browser. If the method requires authentication, a dialog box will pop up to get that information. This is more convenient than running early source code or using cURL, as described later in this chapter.
The POST method does the same thing as GET, but it acquires its results in a different way. Whereas there is an upper limit on the size of a GET query string, a POST request encapsulates the submitted data, allowing more information to be transferred. It treats that bundle of data like an attachment to an email, something separate from and subordinate to the requested URL rather than part of it. Because the data is encapsulated and sent separately from the URL, POST data is not exposed in server logs.
Warning
POST data should not be treated as implicitly secure. It does help guard against simple attacks such as image-based cross-site request forgeries (see http://en.wikipedia.org/wiki/CSRF for more details), but it is only “security by obscurity.”
POST is required for API methods that actually make changes to Twitter’s servers, rather than just retrieving data. This is typical of all APIs and web forms in general, and is not unique to Twitter. In the Twitter API, the following methods require POST request handling:
https://twitter.com/...uses/update.xmlNote
POST requests to the API do not count against the rate limit.
The Twitter API also accommodates a third protocol, the DELETE method. The purpose of this type of HTTP call is to instruct the remote server to remove the requested URL resource. There is no way for the remote client to guarantee that this has been done, however. POST requests work just as well with the API, and in this book we’ll use POST instead of DELETE.
There are only a handful of API methods that will recognize a DELETE request:
One of the bits of information returned to the client in an HTTP request is the status code, a series of three-digit numbers used to communicate the type of success or failure encountered. The Twitter API assigns special meanings to many of these codes, which describe specific outcomes of method requests.
The following are some status codes your application may encounter, and what they likely mean in the context of the API:
- 200—OK
Success! The method request did what you expected it to do.
- 304—Not Modified
Nothing wrong, but nothing to report.
- 400—Bad Request
This can be caused by one of two things: either the request was formatted incorrectly (missing required parameters, unknown method, etc.), or the rate limit has been exceeded. Check the returned text for an explanation.
- 401—Not Authorized
The account (Twitter username or registered email address) or password you used to authenticate to the API isn’t working. Check its accuracy and try again.
- 403—Forbidden
Twitter understood what you want to do, but won’t let you do it. Check the returned text for an explanation.
- 404—Not Found
Probably caused by a typo or incorrect path to the API method you are requesting. You might also get this error when trying to request a nonexistent user.
- 500—Internal Server Error
The Twitter folks may be working under the hood. What you requested is probably OK, but the servers aren’t handling it correctly. Seek counsel from engineers on the Twitter Development Talk Google Group.
- 502—Bad Gateway
Intentional Fail Whale; Twitter is probably rolling out an upgrade.
- 503—Service Unavailable
Unintentional Fail Whale (see the section called “The Rise of the Fail Whale”); there are too many requests for the servers to handle right now.
Twitter will try to return any error messages in the same format being requested for the data, such as this XML version:
Authentication required to request your own timeline. /statuses/user_timeline.xml
The default format is text. Twitter will always try to return some kind of explanation, if it can.
Status codes are an easy way to direct the application logic. Parsing the returned messages will provide specifics and can be helpful for passing along interpretations of errors to the end user, but status codes are easier to access from the HTTP response. They can help direct error handling or confirm success.
Twitter currently accommodates four kinds of formatted data:
- XML
Extensible Markup Language uses semantic tags to wrap data in a structured format. It is extensible because the user can define the structure and kinds of tags; they aren’t simply prescribed, as with HTML. Use of XML to structure data is an accepted way to separate the data layer from the presentation layer and make applications more versatile.
- JSON
Javascript Object Notation is a language-independent text format used primarily to power Ajax applications. With JSON, simple text can be used to represent many different types of data and the relationships between those data types. As with XML, the data is encapsulated in a structured format; however, JSON is considered to be simpler than XML. For more information on how to use JSON, visit http://www.json.org.
- RSS
Really Simple Syndication is a specific form of XML that reflects some standardized tag structures that can be read in a predictable manner. RSS feeds are widespread on blogs, news websites, and services like Twitter.
- Atom
Atom Syndication Format is an alternative to RSS that was created in part to remove the need for legacy support of older protocols. Atom uses a different date and time format than RSS and is more accommodating of modular use and international support.
We’ll use XML in this book, but to switch to JSON, simply change
the URL extension from .xml to
.json in the HTTP request. That’s
what RESTful design principles do for you!
Only a few Twitter API methods make use of the RSS and Atom formats. The following are used on the official Twitter website, allowing people to subscribe to information streams:
Learn more about this topic from Twitter API: Up and Running.
This groundbreaking book provides you with the skills and resources you need to build web applications for Twitter. Perfect for new and casual programmers intrigued by the microblogging, Twitter API: Up and Running carefully explains how each part of Twitter's API works, with detailed examples that show you how to assemble those building blocks into practical and fun web applications.
