Crate egg_mode

A library for interacting with Twitter.

Please see the repository and its enclosed examples for tips on working with this library while it's still in progress.

Getting Started

The very first thing you'll need to do to get access to the Twitter API is to head to Twitter's Application Manager and create an app. Once you've done that, there are two sets of keys immediately available to you. First are the "consumer key" and "consumer secret", that are used to represent you as the application author when signing requests. These keys are given to every single API call regardless of permission level. Related are an "access token" and "access token secret", that can be used to skip the authentication steps if you're only interacting with your own account or with no account in particular. Generally, if you want to read or write to a particular user's stream, you'll need to request authorization and get an access token to work on their behalf.

The process to get an access token for a specific user (with this library) has three basic steps:

1. Log your request with Twitter by getting a request token.
2. Direct the user to grant permission to your application by sending them to an authenticate or authorize URL, depending on the nature of your app.
3. Convert the verifier given by the permission request into an access token.

The process changes some smaller details depending on whether your application is web- or mobile-based, as opposed to desktop-based or in another situation where redirecting users to a web browser and back automatically is difficult or impossible. In the former case where URLs can be used to direct the user into and out of your app, give Twitter a "callback URL" when setting up your request token, and redirect the user to an authenticate URL to grant your app permissions. When the user accepts the request, they will be redirected back to this URL to get back to your app, with the original request token and a verifier given to your app to signify their acceptance.

On the other hand, if you can't use the callback URL in this fashion, you can instead use the "PIN-based Auth" version of the flow. In this version, give a "callback URL" of "oob" when setting up your request token, and use an authorize URL. When the user grants the permissions request in this fashion, they are given a numeric PIN that can be given back to your app to use as a verifier.

Either way, when you have a "verifier" from either of these methods, you can use your Tokens from earlier in the process with that verifier to request an access token. This access token can then be saved and cached for future use.

Response<T>

Every method that calls Twitter and carries rate-limit information wraps its return value in a Response struct, that transmits this information to your app. From there, you can handle the rate-limit information to hold off on that kind of request, or simply grab its response field to get the output of whatever method you called.

Modules

As there are many actions available in the Twitter API, egg-mode divides them roughly into several modules by their shared purpose. Here's a sort of high-level overview, in rough order from "most important" to "less directly used":

Primary actions

These could be considered the "core" actions within the Twitter API that egg-mode has made available.

• tweet: This module lets you act on tweets. Here you can find actions to load a user's timeline, post a new tweet, or like and retweet individual posts.
• user: This module lets you act on users, be it by following or unfollowing them, loading their profile information, blocking or muting them, or showing the relationship between two users.
• search: Due to the complexity of searching for tweets, it gets its own module.
• direct: Here you can work with a user's Direct Messages, either by loading DMs they've sent or received, or by sending new ones.

Secondary actions

These modules still contain direct actions for Twitter, but they can be considered as having more of a helper role than something you might use directly.

• place: Here are actions that look up physical locations that can be attached to tweets, as well at the Place struct that appears on tweets with locations attached.
• service: These are some miscellaneous methods that show information about the Twitter service as a whole, like loading the maximum length of t.co URLs or loading the current Terms of Service or Privacy Policy.

Helper structs

These modules contain some implementations that wrap some pattern seen in multiple "action" modules.

• cursor: This contains a helper trait and some helper structs that allow effective cursoring through certain collections of results from Twitter.
• entities: Whenever some text can be returned that may contain links, hashtags, media, or user mentions, its metadata is parsed into something that lives in this module.
• error: Any interaction with Twitter may result in an error condition, be it from finding a tweet or user that doesn't exist or the network connection being unavailable. All the error types are aggregated into an enum in this module.

Modules

cursor	Types and traits to navigate cursored collections.
direct	Structs and methods for working with direct messages.
entities	Data structures containing extracted URL, mention, tag, and media information.
error	A composite error type for errors that can occur while interacting with Twitter.
place	Types and methods for looking up locations.
search	Structs and methods for searching for tweets.
service	Methods to inquire about the Twitter service itself.
tweet	Structs and functions for working with statuses and timelines.
user	Structs and methods for pulling user information from Twitter.

Structs

Response	A helper struct to wrap response data with accompanying rate limit information.
ResponseIter	Iterator returned by calling .into_iter() on a Response<Vec<T>>.
Token	A key/secret pair representing an OAuth token.

Functions

access_token	With the given OAuth tokens and verifier, ask Twitter for an access Token that can be used to sign further requests to the Twitter API.
authenticate_url	With the given request Token, return a URL to redirect a user to so they can accept or reject an authorization request.
authorize_url	With the given request Token, return a URL that a user can access to accept or reject an authorization request.
request_token	With the given consumer Token, ask Twitter for a request Token that can be used to request access to the user's account.
verify_tokens	If the given tokens are valid, return the user information for the authenticated user.

Type Definitions

WebResponse

Type alias for responses from Twitter.