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

cursor	Types and traits to navigate cursored collections.
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.
search	Structs and methods for searching for tweets.
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.
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.