Module egg_mode::raw[−][src]

Expand description

Raw access to request- and response-building primitives used internally by egg-mode.

The functions and types exposed in this module allow you to access Twitter API functions that aren’t currently wrapped by egg-mode, or to provide parameters to Twitter that egg-mode doesn’t currently use. These functions also allow you to have more power in how you process the data returned by Twitter. In return, much more knowledge of the Twitter API is required to effectively use these functions.

The functions in this module can be divided into two categories: assembling a request, and executing it to get a response. Some wrapper types in egg-mode operate directly on requests, or create their own, so constructors for those types are also exposed here.

To start using the functions in this module, you’ll need a Token from the authentication flow. The parameters to an endpoint are represented by the ParamList type. They’re separated out so that they can be included as part of the OAuth signature given to Twitter as part of the API call. This also means that the URL you give to the request functions should be the base URL, with no parameters.

There are three basic request functions, based on how the endpoint expects to be called:

  • request_get assembles a GET request, with the given parameters appended to the URL as a query string. All GET endpoints that egg-mode currently wraps use this function to encode and sign the request.
  • request_post assembles a POST request, with the given parameters included in the POST body formatted as x-www-form-urlencoded data. Most POST endpoints in the Twitter API are formatted using this function.
  • request_post_json also assembles a POST request, but instead of taking a ParamList, it takes arbitrary data and formats it in the POST body as JSON. The provided data is not used as part of the OAuth signature. At time of writing (between releases 0.14 and 0.15) the only egg-mode endpoint that uses this function is media::set_metadata.

Once you have a Request, you can hand it to the response_* functions in this module to process it. Which one you select depends on how much processing you want egg-mode to do with the response:

  • At the most hands-off end, there’s response_future, which is a small wrapper that just starts the request and hands off the ResponseFuture from hyper to give you the most power over handling the response data.
  • In the middle, there’s response_raw_bytes, which wraps the ResponseFuture to return the headers and response body after inspecting the rate-limit headers and response code, and after inspecting the response to see whether it returned error data from Twitter.
  • Finally there’s response_json, which picks up from response_raw_bytes to parse the response as JSON and deserialize it into the target type, alongside the rate-limit information from the response headers.

In addition, there are request_as_* and response_as_* functions available to format a request using one of the wrappers used in egg-mode. If the endpoint you’re using is one that currently uses one of these wrapper types or returns and accepts data the same way as one of these endpoints, you can use these functions to get the same experience as the existing wrappers in egg-mode. See the documentation for these functions to see their assumptions and requirements.

If you need the ability to assemble a request in a way that request_get, request_post, or request_post_json don’t allow, the RequestBuilder type available in the auth submodule provides the lowest-level control over how a request is built and signed. For more information, see the auth module.

Modules

auth

Facilities to manually assemble signed requests.

types

Types that can be used for deserialization from the raw API.

Structs

ParamList

Represents a list of parameters to a Twitter API call.

Traits

RoundTrip

Types that implement Deserialize either by loading from upstream JSON, or via a “round-trip” serialization.

Functions

request_as_cursor_iter

Assemble a GET request and convert it to a CursorIter.

request_as_tweet_timeline

Assemble a GET request and convert it to a Timeline of tweets.

request_delete

Assemble a signed DELETE request to the given URL with the given parameters.

request_get

Assemble a signed GET request to the given URL with the given parameters.

request_post

Assemble a signed POST request to the given URL with the given parameters.

request_post_json

Assemble a signed POST request to the given URL with the given JSON body.

response_as_stream

Converts the given request into a TwitterStream.

response_empty

Loads the given request and discards the response body after parsing it for rate-limit and error information, returning the rate-limit information from the headers.

response_future

Converts the given request into a raw ResponseFuture from hyper.

response_json

Loads the given request and parses the response as JSON into the given type, including rate-limit headers.

response_raw_bytes

Loads the given request, parses the headers and response for potential errors given by Twitter, and returns the headers and raw bytes returned from the response.

Type Definitions

Headers

A set of headers returned with a response.