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:

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.

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:

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:

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:

For several of the Twitter API methods, it is not enough to just send the URL; the request also requires that some parameter value be included to let Twitter work its magic. The following are descriptions of parameters that may be required for some API methods:

The power and efficiency of the API are increased when you send additional instructions to Twitter to shape what information is returned. In addition to any parameters that a given method may require, there are usually additional options that can be set to filter data before it is returned to you. The following list describes parameters that may be optional for some API methods:

To help developers manage their access to the API, Twitter created a special method to return information about the rate limit status of the authenticating account:

https://twitter.com/...imit_status.xml

Requesting this method does not count against the rate limit and can provide useful information about the current maximum, the number of hits remaining in the current hour, and when the clock will be reset (both in absolute clock time and elapsed seconds). The Check Rate Limit Status method is discussed in the section called “API Administration”.

For most uses of the API, developers can work within the rate limit. However, in some cases, an application will require more than 100 requests at a time in order to provide its functionality. Twitter sometimes makes allowances for this by adding user accounts to a whitelist, where limits are raised or eliminated.

If you are developing an application that requires a lot of requests to the API, you can submit a web form (https://twitter.com/...st_whitelisting) and ask Twitter to be considered for addition to the whitelist of high-volume screen names. This will raise your upper limit from 100 to 20,000 API requests per hour.

This method adds a tweet to the information stream for the authenticated user. In Twitter terminology, this is an update of the current member’s status:

https://twitter.com/...uses/update.xml

To make this URL request function, authentication is required (so that the new status message can be assigned to the correct account). Since it involves a change to the service database and not simply a data grab, the POST method is required to encapsulate the parameter data in this request.

The Post a Tweet method requires one parameter, status, filled with encoded text of no longer than 140 characters. Omitting the message results in no status being published and subsequently no content being returned. When successful, Twitter returns XML containing information about the new status update (see the section called “Status Objects”).

To identify which tool published the tweet—as in “from the web” or “from twitterrific”—there is an optional parameter, source, that can contain the short identifying string registered with Twitter upon request. There is also an optional parameter, in_reply_to_status_id, that can attach this tweet to another specific status update by another user. This will associate the message with the author specified in the in_reply_to_user_id attribute in the status data object. If the reply status ID is not valid, the parameter will be ignored.

After a status update has been published, it can be deleted. However, this can only be done if the authenticated user is also the author of the update to be removed:

https://twitter.com/statuses/destroy/id.xml

The id parameter is required to identify which existing status update is to be deleted—information that is included by referencing the status ID in the request URL (replacing id in the preceding link). If the request is successful, Twitter returns the status object information. This is the same response posting a new tweet will produce (see the previous section). If the status ID is not provided or is invalid, the XML returns an error: “No status found with that ID” (see the section called “Hash Objects”).

Deleting a tweet is a practice that should be discouraged. Part of the value of Twitter is that it provides a long-term record of the little things we do and say, including the mistakes. Although there will almost certainly be times when you will need to remove a tweet you’ve posted, it is important to realize that your timeline is not an inbox. Leave your footprints for posterity.

This method was created to enable us to view the details for a single status update:

https://twitter.com/statuses/show/id.xml

This type of request returns XML structured in the same way as that returned by the publishing methods described earlier, including a description of the update author as well as the message itself (see the section called “Status Objects”). If the status ID is not provided or is invalid, the XML returns an error.

Authentication is not needed, provided the tweet is public. To view protected status updates made by private authors who have authorized you to do so, you must provide a valid username and password.

This method returns the 20 most recent status updates from public accounts in Twitter:

https://twitter.com/...ic_timeline.xml

Authentication is not required and thus retrieval from the public timeline does not count against the API rate limit, even if you do authenticate.

A successful request returns information about the recent status updates, following the same format and structure as that returned by the publishing methods, but with multiple status data objects contained within a XML wrapper (see the section called “Status Objects”).

The public timeline is not a complete picture of all Twitter traffic. An estimated 10% of all user accounts are private accounts;^[66] those users’ status updates are available only to approved people and are not included in the public timeline. Additionally, Twitter requires that an account be minimally configured to include a custom user icon for it to be part of the public timeline.

Similar to the one for the public timeline, there is a method in the API to retrieve recent tweets from the perspective of a specific user. Calling the View a Friends Timeline method returns the 20 most recent status updates posted by the authenticated user and the authors that user follows:

https://twitter.com/...ds_timeline.xml

This data is the same stuff you’ll see on the home page after logging into the Twitter website. A successful request returns XML structurally identical to that of the data returned by the View the Public Timeline method.

There are several optional parameters that can be used to filter the data that is returned. Three of them—since, since_id, and count—change the number of status updates returned by truncating older tweets. The since parameter gives the API a certain point in time to use as the cutoff, whereas the since_id parameter identifies a specific status ID (presumably the last one your application successfully captured). The count parameter specifies the number of recent tweets to return. When creating applications that monitor the activity of an account, these are great parameters to use to avoid redundancy.

The page parameter allows the application to navigate further back than just the 20 tweets available on the first page of the friends timeline. Current restrictions maximize the archive at 200 tweets, which translates to 10 pages of timeline content.

A third view of the Twitter timeline is the user archive. This stream contains just the tweets published by a single author. The View an Individual Timeline method returns the 20 most recent status updates posted by the authenticated user:

https://twitter.com/...er_timeline.xml

It’s also possible to request another user’s timeline by adding another level to the URL path and identifying that user, as in:

https://twitter.com/.../user_timeline/id.xml

The id parameter is replaced with the user’s ID or username. This is the same content one would see by visiting a member’s Twitter profile page.

Without authentication or inclusion of a public user ID, this method returns a variation of the standard error message: “Authentication required to request your own timeline” (see the section called “Hash Objects”).

Successful requests respond with an array of status data objects (see the section called “Status Objects”), as is the case with other timeline methods. The results can be filtered in the same way as those for the friends timeline, using since, since_id, count, and page.

Replies are status updates that reference another Twitter member. The convention, culled from the old days of Instant Relay Chat (IRC), is to precede the username with the @ symbol. Although Twitter wasn’t originally meant for conversation, many people post status updates as replies to direct conversation to particular users.

These replies can be viewed as a separate timeline by using a special API method:

https://twitter.com/...ses/replies.xml

This method returns the 20 most recent @ replies addressing the authenticated user. These will include status updates posted by people the user is not following if the account configuration is set to include replies from all users.

Twitter currently allows retrieval of up to 40 pages, or 800 replies, by using the optional page parameter. This method also facilitates retrieval of the freshest replies by recognizing the since and since_id parameters.

Successful requests return the standard status data object array, as with the timeline methods discussed previously.

In Twitter, you can create a bookmark (called a “favorite”) to mark a status update you want to remember. There is a separate view of the timeline that returns the 20 most recent “favorited” statuses for the authenticated user:

https://twitter.com/favorites.xml

As with the regular user timeline, you can specify an id in the request URL to get a list of favorites for a user other than the one whose credentials were used to authenticate to the API:

https://twitter.com/...tes/kmakice.xml

If that user has a public account, the information can be retrieved without authenticating. Pagination through the page parameter is the only option available to let the application navigate back to see the full list of all favorited tweets.

To create a new bookmark, you must specify the ID of the status update to be favorited in the request URL:

https://twitter.com/favorites/create/id.xml

This command returns a single status data object for the favorite message when successful, and a “Not found” error if the status message doesn’t exist or is inaccessible to the authenticated user. The new favorite will be associated with the authenticated user.

Deleting a bookmark doesn’t delete the status message (how could it, if you’ve marked other people’s tweets as favorites?), but it does remove the flag you have previously set to remind you how much you liked the content. Times change, and you may need to distance yourself from the memory of a particular update. By using this method, you can un-favorite a specified status message:

https://twitter.com/favorites/destroy/id.xml

The id of an existing message must be included in the request URL to indicate the message you now want to forget. If you try to un-favorite a message that doesn’t exist or isn’t currently a favorite of the authenticated user, a “Not found” error message will be returned (see the section called “Hash Objects”). Success brings one last reminder in the form of a single status data object that describes the message and its author.

People are the main unit of currency in a follow network. Each member contributes to the collective wisdom, by talking about what is important to them at a given moment and also by identifying other people of interest. When you encounter a new person on Twitter, looking at her profile is one way you can decide whether you want to follow her.

The Show Member Profile method gives you all the basic profile information you have already seen attached to the status data objects, plus a lot of new information about the specified user. Most importantly, this is the method you need to use to find out statistics such as the number of updates a user has posted and how many people that member is following:

https://twitter.com/users/show/id.xml

Even to access your own profile information, the id needs to reflect your username or user ID and be included in the request URL.

https://twitter.com/users/show/id.xml

https://twitter.com/users/id.xml

Alternatively, you can use the email parameter to get profile data, as in:

https://twitter.com/...akice@gmail.com

Doing so allows you to look up a Twitter member’s account information by referencing the email address used to register that account (for public accounts, authentication is not required). Private accounts are protected from this search, unless the authenticating user has been granted access to those accounts. Twitter also added two other parameters—user_id and screen_name—that can identify which member account you want returned. Either can be used as a query string variable (e.g., https://twitter.com/...xml?user_id=415) to help disambiguate between user IDs and screen names that are composed entirely of numbers. id assumes a number is a user ID and returns that, which made it impossible to view some profiles. The two newer parameters were added to give you more control and in fact take precedence over use of id.

The detail in the XML gives you a lot of information about the design of the specified member’s profile page, including the style scheme used on the page and whether it has a background tile. Although you may not be too interested in what the member’s profile page looks like, you also get details on the user’s time zone setting, the number of status messages that user has bookmarked (favorites), the total number of updates he has posted, and the number of other people he is following. The profile data also includes information about the member’s latest update (see the section called “User Objects”).

If the request is sent with authentication, a couple of extra fields are available in the XML:

 false

 false

This information has to do with the relationship between the two Twitter users (the authenticated user and the user identified by the id parameter). In this example, the authenticated user is not following the requested user. This information will appear for unauthenticated requests as well, defaulting to a following value of true and a notifications value of false.

The more important half of the follow network is the list of people you follow. Although it is great to have a throng of devoted fans hanging on every word you tweet, your experience with Twitter will be affected much more by the content you see than by how many people read your own tweets.

The API provides a method to show who is contributing to your personal information stream:

https://twitter.com/...ses/friends.xml

The following lists are available for any public account. Simply including the id parameter in the request URL (username or user ID) without authenticating will allow you to look at how another member’s information stream is composed:

https://twitter.com/...nds/kmakice.xml

Accessing this information for a private account, however, requires not only authentication but also the permission of the account holder, which you gain by virtue of being allowed to follow that user’s status updates.

The View Members Being Followed method returns a list of up to 100 Twitter members that the authenticating or identified user is following, with the members who have updated most recently appearing first. If the user is following more than 100 members, you can access the full list by using the page parameter to navigate to less active authors. Each successive page will include the next 100 users, until the list of followed authors is exhausted.

This method also allows use of the since parameter, which is quite useful for keeping tabs on just the latest changes to a following list. You can specify a URL-encoded date and time (no more than 24 hours old) and have Twitter return only the latest additions. A successful request returns an array of user data objects (see the section called “User Objects”).

Each user’s Twitter profile information can be found in the structured data, including a flag that indicates whether the account is private (false) and how many followers that person boasts.

The other half of your follow network consists of the people who find the minutiae of your life so interesting that they decide to hang on every word you tweet. Followers are people who include your content in their information streams, and there is a nice method in the API to request the list of followers:

https://twitter.com/...s/followers.xml

A successful request again gets the array of user profile data, but the ordering is different from that of the following list: Twitter currently lists followers according to when they signed up for Twitter, with the newest members appearing at the top of the list.

If you have a large number of followers, it’s likely that while a lot of information about your new followers will be on the first page of results, not all of it will be. Any time an established Twitter user follows you, that information will be buried deep in the pagination; to find it, you’ll have to use the page parameter.

The list of people who follow you is a much more guarded secret than the list of those you follow. For starters, you must be authenticated in order to view anyone else’s list. If you are not, or if the person whose information you are trying to get has a protected account and is not someone you follow, an authorization error will result:

 Not authorized

 /statuses/followers/cmakice.xml

About half of the members of the Twitterverse will have more followers than people being followed. The latter is in one’s control, but the former is not. For that reason, exploring someone else’s following list—where everyone has been vetted in some minimal fashion—is probably more useful than looking at their followers.

One of the big obstacles facing developers interested in social graphs of Twitter activity is how to identify all the members of a follow network. Until recently, the only way to get a list of everyone following a given member was to loop through multiple requests of the View Followers method. Now, there is an easier way to do this:

https://twitter.com/followers/ids.xml

This method returns a simple XML list of the user IDs of all of the authenticating user’s followers. No other information is included, such as those members’ latest tweets or even their usernames. This method makes it much easier to keep tabs on social relationships, but the trade-off is you don’t get any extraneous information.

The Get All Followers method requires authentication. To get a list of followers for someone other than the authenticating user, add that member’s username or ID to the request:

https://twitter.com/followers/ids/id.xml

If you don’t authenticate with the API request, you’ll get a message like, “Could not authenticate you.”

The same kind of method is available for the other half of the follow network, too. You can get a simple XML list of the user IDs of all the people you choose to follow by making a single API request:

https://twitter.com/friends/ids.xml

This method does not require authentication, unless the person whose list you want to access has a protected account.

To build your follow network, you need a method for adding a friend. This method allows you to do that, as well as to optionally add this person to your notifications list to receive their tweets on your cell phone.

To follow another user, you need to create a relationship between the authenticated user and some other user, identified with the id parameter:

https://twitter.com/...ndships/create/id.xml

What comes back when this request is successful is the short-form profile information for the new friend. The request will only be successful, though, if the relationship doesn’t already exist. If you try to follow someone already on your list, Twitter returns an error: “Could not follow user: id is already on your list” (see the section called “Hash Objects”).

There is an optional parameter—follow—that lets you have a two-for-one by automatically adding your new friend to your notifications list. If this parameter is present and set to a value of true, this member will have notifications enabled so you can immediately start receiving her tweets on your cell phone. This is the same action performed by the Turn On Notification method described in the section called “Member Account”.

Following another account has a few side effects. First, that person’s content is included in your information stream. This happens immediately if the account is public, but only after approval if the account is protected.

Second, most accounts are configured to send a notification when a new follower is added. This is an effective way to expand your follow network, because odds are good that someone interested in what you are tweeting will be interesting to you. Conversely, it is possible that the act of following someone will result in that person following you.

Does your new friend tweet too much about Barney the Dinosaur? No problem. Simply unfollow that person to remove his content from your personal information stream:

https://twitter.com/...dships/destroy/id.xml

The format and response are the same as for the follow request, except you are removing rather than adding a tweep. If you are not already following that member, then Twitter sends an error: “You are not friends with the specified user” (see the section called “Hash Objects”).

Unfollowing is one of the basic rights of a Twitter member and one of the things that makes the experience so rich. The sharing of information on Twitter is technically decoupled, so you can choose to follow someone who doesn’t follow you. Although reciprocation happens frequently, it isn’t a requirement in Twitter as it is in Facebook and other social networks.

No two information streams are alike, and the same goes for users. What might seem to you a paltry rate of tweeting could be overwhelming to someone else. Use the Unfollow a Member method to adjust your flow of status updates, and try not to take it personally when someone chooses not to follow you.

Wading through all of the pages of your follow network lists, or even requesting profile information for another member to find out whether you’re following that person, is an awkward way to investigate the connections in your follow network. Fortunately, Twitter provides a simple method that can be used to check whether one user is following another:

https://twitter.com/...hips/exists.xml

This method requires two variables—user_a and user_b—that contain the user IDs or screen names for the two Twitter members whose relationship you want to confirm. For example:

https://twitter.com/...&user_b=kmakice

If the check is successful, Twitter responds with simple output (see the section called “Response Objects”).

If the first user is not following the second—because either the relationship or one of the users does not exist—the value of the returned field will be false. If the users are not included in the request, Twitter will return an error: “Two user ids or screen_names must be supplied” (see the section called “Hash Objects”).

Since the follower relationship is not coupled (i.e., you can follow someone who doesn’t follow you), the order of these two IDs is very important. In an asymmetrical relationship, you will get opposite results depending on which member is listed first as user_a.

The great thing about Twitter is that you can choose to unfollow anyone you find too annoying, too noisy, or too obsessed with the sweet, sweet taste of Edwardo’s Pizza in Chicago. Sigh. Those aren’t necessarily reasons to block someone, however. A block is a more serious way to distance yourself from another user.

When you block a user, you aren’t blocking her from seeing your updates. A public account is still a public account. Your status updates, the list of people you follow, and your profile information all remain readily accessible to that user. However, blocking does make it impossible for that person to follow you and keeps your Twitter icon off her profile page.

The API method to create a block requires authentication and inclusion of the dissed user’s id in the request URL:

https://twitter.com/blocks/create/id.xml

If this action is successful, the short-form profile data object for the blocked user is returned.

If you block another user, that user will not be notified. Twitter is intentionally subtle in how it conveys the action back to the victim of a block: if that person tries to follow you, he will get an ambiguous error on your profile page. However, the API is much more straightforward about what has happened, providing this message: “Could not follow user: You have been blocked from following this account at the request of the user” (see the section called “Hash Objects”).

For private accounts, of course, the de facto state is that everyone is effectively blocked. You can only include a private member’s status updates in your information stream if the private account holder gives you the OK.

All good things must come to an end. This, too, shall pass. What goes around comes around. Pick your colloquialism, but what I’m trying to say is: blocks aren’t permanent.

You can remove a previous block on another user by using a different method in the API:

https://twitter.com/blocks/destroy/id.xml

This authenticated POST request will find the user account specified in the URL (id) and remove the block that prevents that person from following your status update stream. When successful, it returns the short-form profile for the specified user.

Imposing a block removes any follower relationships between the authenticated user and the victim of the block, so removing a block on someone you used to follow will not reinstate that relationship—the user will remain out of your stream until you follow her (or she tries to follow you) again. The user will not be informed that the block has been removed; she will only realize this if she’s told or if she tries to follow you again and succeeds.

If you choose to follow someone whom you currently have blocked, the block will be removed automatically. You do not have to explicitly remove the block in order to follow the victim; that happens automatically with a follow request.

A separate tab in the Twitter interface handles the flow of direct messages, which will occur at a much slower rate than status updates. You can set your account to send you direct message notifications via text or email, and clients such as Twitterrific use the API to bring the messages into a single information stream.

There is an API method to list all of the messages the authenticated user has received, which are returned in groups of 20:

https://twitter.com/...ct_messages.xml

This method recognizes some navigation and filtering parameters to control which page you retrieve (page) and to look for only the most recent messages (since, since_id).

The returned list is an array of direct message data objects, each with three distinct parts. The information about the message has some overlap with the information for a status update, in that it provides a record ID, the message text, and the creation date. In addition to describing the author, though, it must also report who the recipient is. Embedded in the direct message object is the familiar short-form profile information about both the sender and the receiver of the direct message (see the section called “Message Objects”).

Since direct messages are not as common as status updates, it is not unusual for an account to have no record of direct messages being received. In that case, the API returns an empty object in the XML (see the section called “Response Objects”).

Twitter also lets you keep track of the direct messages you have sent. A second messaging method lets you access your outgoing message archive:

https://twitter.com/...ssages/sent.xml

Similar to the method for listing received messages, this method returns the 20 most recent direct messages sent by the authenticated user. The same optional parameters (since, since_id, and page) are available to adjust which part of the full list of messages is pulled out of the API.

You can create a new direct message using a special method provided by Twitter:

https://twitter.com/...essages/new.xml

This method requires two parameters: the user parameter identifies who will receive your private bit of wisdom, and the text parameter is your private bit of wisdom. The message must be URL-encoded and is limited to the signature 140 characters. Like all requests to change the Twitter database, this method requires a POST.

If successful, Twitter returns a single direct message data object containing the same information described in the communication methods discussed earlier. Mistakes in the format of the request will result in an “Invalid request” error. Because the sender and the receiver of the message must be following each other, Twitter will return an error if that is not the case: “Can’t send direct messages to users who aren’t your friend” (see the section called “Hash Objects”).

You can also send direct messages using the Post a Tweet method:

https://twitter.com/...uses/update.xml

You must start the status text with d username to direct the message to the person you want. This is the same function the text-based commands perform in Twitter clients.

Not everyone likes to keep a permanent archive of all of the little messages they send and receive. There is no search mechanism for these messages, so it is sometimes helpful to prune out the ones you don’t want to keep (assuming you want to keep any at all).

Deleting an existing direct message is as easy as using another API method:

https://twitter.com/...ssages/destroy/id.xml

This method follows more or less the same procedures as that of a status update removal: you identify the ID of the message to be removed and authenticate using the account credentials of either the sender or the receiver. If successful, you will get the message information as a data object.

Until recently, only the receiver of a message had the power to delete it. However, you are now also able to delete messages that you yourself sent—the recipients are no longer the only ones with the power to remove your missives from the face of the Twitosphere.

You can only destroy what has first been created. If you send a request to delete a received message using an invalid ID, Twitter will let you know it can’t do it: “No direct message with that ID found” (see the section called “Hash Objects”).

Surprisingly, there is no method that allows you to retrieve a single direct message. One might expect something like this to work:

https://twitter.com/statuses/show/id.xml

https://twitter.com/...-messages/show/id.xml

Attempting such a request, however, results in the following response from the API:

<html><body>You are being 

 redirected.

That means if you want to get information on a particular message, you have to either page through the full list until you find it, or delete it and get the single direct-message data object one last time.

For a long time, one of the few profile changes you could make through the API was to set your location. Prior to this method being added to the arsenal, the only way to change this text was to log into the Twitter website and manually edit your account settings there. That was before the iPhone, BrightKite, and other location-aware systems started integrating with Twitter.

The Update Member Location method allows you to change the location field in the authenticated user’s profile through the API:

https://twitter.com/...te_location.xml

This method has one required parameter, location, which contains the new text you want to place on your user profile, replacing whatever is currently in the location field.

Omitting the location parameter will result in the current location being reset to an empty string, rather than generating an error. The short-form user profile data object returned by the API indicates success.

Many other bits of information are displayed on the member profile pages on the Twitter website. This method allows you to change some of that information through the API:

https://twitter.com/...ate_profile.xml

All of the parameters for this method are related to fields found under the “Account” tab of the Settings page on the Twitter website. Only specified parameters will result in updates to the profile. A user object is returned with the new information to indicate success (see the section called “User Objects”).

This method allows for several parameters, including location (to update the user’s location, which used to be handled through the deprecated method discussed in the preceding section). You can also adjust the full name of the account holder (name), the URL pointing to a company or personal web page (url), the email address associated with the account (email), and the short text statement about the account holder (description). Length limits of between 40 and 160 characters are imposed, depending on the parameter.

Although the number of tweets posted from the Twitter website has decreased to under 50% of the full archive, most active users visit the main website on a regular (perhaps even daily) basis to check out the profiles of new followers. Not surprisingly, an eye for design is on the rise. The trend began in 2008 with a Photoshop template that was virally distributed to extend the profile information by using a background image. Later that year, Twitter added themes to allow members to differentiate their web pages’ appearances, even if they didn’t want to go as far as designing a custom look. Every day, the visuals matter a little more.

The Update Profile Colors method lets you make changes to the color scheme used on your member page. The five available parameters are the same ones you would find under the “Design” tab on the Settings page of the main website. The “change design colors” link at the bottom of that page reveals fields to control the color of the profile background (profile_background_color), text (profile_text_color), links (profile_link_color), sidebar shading (profile_sidebar_fill_color), and border (profile_sidebar_border_color). This method accepts parameters to change the values of each of those fields:

https://twitter.com/...file_colors.xml

All values have to be sent as hexadecimal, either the short (fff) or long (ffffff) form. Because this method deals with changing things on the Twitter server, it requires a POST and is not charged against your rate limit. The method returns a user object with the new information (see the section called “User Objects”).

Changing the background color will not necessarily lead to that color being seen. If the account already has a background image in place, the web page will use that instead; the background image has to be removed before a change to the background color will be visible.

One of the early e-business ventures dealing with advertising on Twitter was Twittads. This company allows individuals to set a price for how much their Twitter profiles are worth and sell ads to display as their background images for a given period of time. This method can be used to automate that process, switching the advertising for you to make sure it gets done.

This method accepts a required image parameter to set the authenticating member’s theme with a new background graphic:

https://twitter.com/...round_image.xml

The image parameter expects the raw multipart data as its value, not simply a URL linking to an existing file—even though that is what you get from Twitter in the user object XML that is returned (see the section called “User Objects”). The graphic can be in GIF, JPG, or PNG format. The background image can have a maximum of 2,048 pixels and the file must be smaller than 800 KB. The file size is a firm limit, but larger pixel sizes will be scaled down to fit.

The background image on a member’s profile page can be displayed as a fixed image attached to the upper-left corner of the browser window, or it can be tiled, which means the image is repeated again and again to fill the entire window. You currently have to go back to the website to check a box for tiling, and unless you replace it with another file through the API, visiting the site is also the only way to remove a background image. At the time of this writing, Twitter doesn’t provide a way through the API to either remove a background picture or have the site tile it.

In late 2008, Twitter Patterns—a site by designer Natalie Jost of olivemanna—launched with a gallery of high-quality downloadable background images for users to upload to Twitter. Although as of this writing no tools are available to create custom themes, it isn’t much of a leap to believe that these newest API methods that facilitate changing the design of Twitter profile pages will lead to support for such tools in 2009.

curl -k -F 'image=@filename.jpg;type=image/jpeg' -u 

yourusername:yourpassword -H 'Expect:' 

https://twitter.com/...ofile_image.xml

Twitter also provides a method to change your profile image (the picture shown with your tweets). As is the case with the Update Background Image method, this method requires an image parameter:

https://twitter.com/...ofile_image.xml

The profile picture is usually quite a bit smaller than the background image for the member profile page, and thus it has smaller maximum values: the GIF, JPG, or PNG file can have a maximum of 500 pixels and must be smaller than 700 KB. Larger pixel dimensions will be scaled down, but bigger files are rejected. Twitter typically stores three versions of every profile picture: the full-sized picture uploaded by the user; the big version used on the profile page (with a _bigger suffix); and the regular version (with a _normal suffix) for display with each tweet.

Most errors are trapped and explained with a vague message: “There was a problem with your picture. Probably too big.” (See the section called “Hash Objects”.) Look for a status code of 200 to let you know whether you were successful. You can also check the website; the image changes are immediate, if successful.

Another configuration setting handled through the API is where you want status updates from the people you follow to be sent:

https://twitter.com/...very_device.xml

This method requires one parameter, device, which can contain one of only three possible options: once set, the authenticated user will be configured to receive status updates as text messages on a cell phone (sms), via a chat client (im), or neither (none).

Routing your Twitter information stream through your mobile phone is an acquired taste. For some people, this is the only interface they use. For others, phone notifications provide a way to filter down the larger following list to just a handful of closely watched friends (as described in the next section).

The API response for a successful edit of the delivery device is the short-form profile data object for the authenticating user (see the section called “User Objects”). If you omit the required parameters or pass along a value that isn’t one of the approved devices (say, device=cow), an error will be returned: “You must specify a parameter named ‘device’ with a value of one of: sms, im, none” (see the section called “Hash Objects”).

If you decide you do want your information streamed to your cell phone, Twitter lets you customize which members of your following list are included:

https://twitter.com/...cations/follow/id.xml

This method will enable the notification setting for the individual user identified in id and will start sending that user’s status updates to the device set with the Update the Delivery Device method.

Success is once again signified with XML containing the specified user’s short-form profile. If you attempt to add notifications for a user you do not follow, or one for whom you have already enabled them, an error will be reported: “There was a problem following the specified user” (see the section called “Hash Objects”).

The evil twin to this method is Turn Off Notification, which disables notifications for the user identified in the request URL:

https://twitter.com/...ications/leave/id.xml

Device notification toggles can cover receipt of direct messages, too. There are two criteria for receiving direct messages from a specific user on your phone: you must have included that user in your notifications list by turning on notification, and direct messages must be selected in the Devices tab in the Settings section of the Twitter website. This latter control is buried in a pull-down menu that appears only after you successfully register your cell phone number with your Twitter account.

Sometimes coding is a nightmare. Things don’t work, and you don’t know why. When that happens, it helps to step back and check whether all your equipment is properly connected. Twitter helps you do this with a simple API method to ping the system:

https://twitter.com/help/test.xml

This method does nothing except return a simple string—an appropriate HTTP status code along with a Boolean (see the section called “Response Objects”).

If you get a status code of 200, the problem is likely buried somewhere in your code. If you get an HTTP error, stop deconstructing your programming skills and figure out what’s keeping you from the API.

One of the more helpful methods to incorporate into your application is the credentials check:

https://twitter.com/...credentials.xml

This method returns a 200 status code if the username and password you plan to use with other methods is valid. The XML response is a user object for the authenticating user (see the section called “User Objects”).

If your authentication doesn’t work, for whatever reason, Twitter will let you know with an error message: “Could not authenticate you” (see the section called “Hash Objects”).

Although you could figure out whether your username and password work simply by trying any method that requires authentication, this method is the preferred way of verifying credentials. It has less overhead than most of the other methods and is easier to use in the code logic.

One of the other obstacles your application may encounter—especially if you expect to perform many data requests in rapid succession—is the error that says you have been cut off:

Rate limit exceeded. Clients may not make more than

	100 requests per hour

When that happens, you are at the mercy of the clock. The API won’t give you the things you want until the hour is up, leaving you and your users hanging.

Twitter created a method specifically to check on the status of your rate limit, providing a great tool to help you anticipate the problem and manage how your application will deal with the bad news:

https://twitter.com/...imit_status.xml

This method returns a short data object filled with numbers and dates (see the section called “Hash Objects”) that will tell you how long you have to wait until you can start making API requests again. A common coding strategy is to check the rate limit status once at the beginning of the application run, and then keep a counter going to let PHP know when to stop bugging the API for data. This approach enables you to gracefully pause or halt the application before bumping into the error from Twitter.

This method doesn’t require authentication, but even if you do authenticate the request it does not count against the rate limit for the account you are checking. If you don’t provide user credentials, it returns the tally for the requesting IP address.

It is good practice to follow a credentials check (Verify Credentials) with an initial rate limit check. If the account is already spent for the hour, you can gracefully exit the program and ask the user to try again later. Otherwise, you can count down the remaining hits to the API and let the user know, once the limit is hit, that the processing will take a while.

For applications that manage user sessions—which are typical of publishing clients—Twitter created a method to clean up the access and make sure the authenticated user is logged out:

https://twitter.com/...end_session.xml

Success is reported with the following XML message: “Logged out” (see the section called “Hash Objects”).

Ignoring for the moment the means by which you make the request, searching with the API is very similar to conducting any search through a website. You need to know what keywords you want to find and how you want the results returned to you.

The request method for tweet searches uses a slightly different URL, with the required q parameter added to the end as an encoded string:

http://search.twitte.../search.atom?q=query

That q parameter is very powerful. Depending on what you put into it, it can be a great filter for the tweet corpus. Each query string has to be encoded for travel in the GET request.

http://search.twitte.../search.atom?q=Go+Bears

http://search.twitte.../search.atom?q=%40aboy

http://search.twitte.../search.atom?q=%23superbowl

http://search.twitte.../search.atom?q=existence+%3F

http://search.twitte.../search.atom?q=sometimes+%3A)

http://search.twitte.../search.atom?q=sometimes+%3A(

http://search.twitter.com/search?q=slouching+near%3Abethlehem

http://search.twitter.com/search?q=pizza+near%3ABloomington%2C+Indiana+within%3A1mi

http://search.twitte.../search.atom?q=fluffy+kitten+filter%3Alinks

http://search.twitte.../search.atom?q=Fail+Whale+since%3A2008-09-01

http://search.twitte.../search.atom?q=olympics+until%3A2008-08-08

http://search.twitte.../search.atom?q=from%3Ahere

http://search.twitte.../search.atom?q=to%3Aeternity

http://search.twitte.../search.atom?q=Fail+Whale

http://search.twitte.../search.atom?q="Fail+Whale"

http://search.twitte.../search.atom?q=Fail+OR+Whale

http://search.twitte.../search.atom?q=Bears+-Chicago

http://search.twitte...h.atom?geocode=31.12345%2C-88.98765%2C1km

Finally, the Twitter API includes a method that returns the top 10 descriptive keywords that are currently being used on Twitter. The response includes the time of the request, the name of each trending topic, and the URL to the Twitter search results page for that topic. Currently, the only supported format for this method is JSON. The callback parameter is supported, however.

The request URL for this method is:

http://search.twitter.com/trends.json

The most obvious thing a hacker can do is deny you access to your own Twitter account. There are failsafes, however, in the form of Twitter’s great customer service and a historical willingness to help people reclaim their identities. Twitter keeps backups of your data, so even if you are blocked out for a day, there is nothing irreparable about it. Also, Twitter allows only one user account per email address, making this an unattractive target.

Malicious actions in this category include:

Some information isn’t available without your Twitter authentication. For example, if your account is compromised, people who protect their accounts and trust you enough to allow you to follow what they post will be vulnerable to the imposter coming in and capturing their tweets.

Among the account settings, the most appealing bit of information is probably the phone number you use for your mobile updates. This could be a personal number that might not be widely distributed or even published elsewhere. A hacker could also access all of the private messages you have exchanged with others in your group. If you aren’t in the practice of deleting them, those messages might contain sensitive information about you or those with whom you converse.

Malicious actions in this category include:

Other changes a hacker could make are hidden from view. In mass, compromised accounts could be scanned for blocks on a spammer account, which could then be removed to force the users to follow that account. Not many people use favorites on Twitter, nor do these bookmarks have much value yet for third-party developers. However, if that changes, a hacker could target a few preferred tweets with marketing links and make sure they appear on everyone’s favorites list.

These actions are difficult to monitor, especially since they can all take place through API interactions, without the account holder knowing what is happening.

Actions in this category include:

Of course, some attacks can be quite visible, such as the January 2009 hacks that posted prank status updates to the timelines of a couple of dozen Twitter celebrities.^[72]

Less obvious but equally visible would be gaining access to the compromised member’s profile page to upload a new avatar or background image. The hacker could also make changes to the web link or description stored in the member profile, or even change your profile picture (although that is much more likely to be noticed, and thus quickly corrected). Unless you visit your own profile web page regularly, you might not notice other changes to your page.

Malicious actions in this category include:

An authenticated user can remove content. Deleting a recent public tweet may or may not be noticed, but odds are much greater that direct messages and old tweets won’t be reviewed as frequently. There isn’t much incentive for a phisher to do this—it’s the electronic equivalent of knocking down someone’s mailbox as you drive by. Presumably, Twitter could restore everything to an earlier state and fix the damage.

What might be more difficult to restore is damage to a reputation. For example, a specific member could be targeted with a massive blocking campaign using a number of stolen accounts, causing some reputation problems or damaging relationships.

Malicious actions in this category include:

If you targeted a specific user, an action such as turning off device notifications—or scheduling them to only show up at 2 a.m.—might be disruptive enough to cost that person sleep or make him miss a big meeting. Most of the changes in this category, however, are merely annoyances that would probably damage Twitter’s reputation more than the individual.

Malicious actions in this category include:

If there is one truly scary thing about a compromised Twitter account, it probably isn’t to do with posting to the public timeline or messing with account settings. The biggest weapon available to a hacker in a compromised account is trust.

The New Year’s phishing problems in early 2009 are a prime example of what can happen when someone communicates with your friends through direct messages. The probability that someone you know will click on a link because they think the recommendation is coming from you is quite high. A direct message is dripping with trust by definition, since the victim has chosen to follow you, and direct messages are comparatively rare and therefore stand out.

There’s only one malicious action in this category, but it’s a biggie: