README.rdoc

grackle

DESCRIPTION

Grackle is a lightweight Ruby wrapper around the Twitter REST API. It's
based on my experience using the Twitter API to build tweetreach.com. The main goal of Grackle
is to never require a release when the Twitter API changes (which it often
does) or in the face of a particular Twitter API bug. As such it's
somewhat different from other Twitter API libraries. It doesn't try to
hide the Twitter “methods” under an access layer nor does it introduce
concrete classes for the various objects returned by Twitter. Instead,
calls to the Grackle client map directly to Twitter API URLs. The objects
returned by API calls are generated as OpenStructs on the fly and make no
assumptions about the presence or absence of any particular attributes.
Taking this approach means that changes to URLs used by Twitter, parameters
required by those URLs or return values will not require a new release. It
will potentially require, however, some modifications to your code that
uses Grackle.

Support and Announcements

The preferred forum for questions and discussions is the Google group at groups.google.com/group/gracklerb.
You can email me directly or @reply me on Twitter, but the group is better
since the questions and responses will be available to everyone. I'll
also make announcements there. There are some examples on the wiki at wiki.github.com/hayesdavis/grackle.
If you prefer your information in 140 characters, follow @gracklerb.

Twitter API 1.1 and Grackle 0.3.0

Grackle 0.3.0 defaults to Twitter API 1.1 out of the box. If you have code
that still relies on API 1.0, you can upgrade Grackle and still use API 1.0
by specifying that the client use the :v1 API:

See Grackle::Client for more information about valid arguments to the
constructor. It's quite configurable. Among other things, you can turn
on ssl and specify custom headers. The calls below are pretty much as
simple as it gets.

Grackle Method Syntax

Grackle uses a method syntax that corresponds to the Twitter API URLs with
a few twists. Where you would have a slash in a Twitter URL, that becomes
a “.” in a chained set of Grackle method calls. Each call in the method
chain is used to build Twitter URL path until a particular call is
encountered which causes the request to be sent. Methods which will cause a
request to be execute include:

A method call ending in “?” will cause an HTTP GET to be executed

A method call ending in “!” will cause an HTTP POST to be executed

If a valid format such as .json, .xml, .rss or .atom is encounted, a get
will be executed with that format

A format method can also include a ? or ! to determine GET or POST in that
format respectively

GETting Data

The preferred and simplest way of executing a GET is to use the “?” method
notation. This will use the default client format (usually JSON, but see
Formats section below):

Toggling APIs

As of Grackle 0.3.0, the Grackle::Client sends all requests to the 1.1
Twitter API by default. If you want to send requests to the Twitter 1.0 API
(which has been deprecated by Twitter and will be unavailable after May
7th, 2013), just use the Grackle::Client#api= method and set it to :v1. To
toggle back, set it to :v1_1. All requests made after setting this
attribute will go to that API.

For convenience, you can also set the desired API in the Client
constructor:

client = Grackle::Client.new(:api=>:v1)

If you want to make a specific request to one API and not change the
Client's overall api setting beyond that request, you can use the
bracket syntax like so:

DEPRECATION NOTICE: The :rest API key (pointing to twitter.com), the
:search API key (pointing to search.twitter.com) and the :v1 API key
(pointing to api.twitter.com/1) have all been deprecated in favor of the
the :v1_1 API (pointing to api.twitter.com/1.1).

Parameter handling

All parameters are URL encoded as necessary.

If you use a File object as a parameter it will be POSTed to Twitter in a
multipart request.

If you use a Time object as a parameter, .httpdate will be called on it and
that value will be used

Return Values

Regardless of the format used, Grackle returns an OpenStruct (actually a
Grackle::TwitterStruct) of data. The attributes available on these structs
correspond to the data returned by Twitter.

Rate Limits and the Response

The Grackle client has a response method which is populated with
information about the most recent response received as a result of a
request. This response contains the requested URI, the HTTP status code, a
subset of the response headers and the raw response body. The response
headers are the most useful because they can be used to retrieve the rate
limit information that Twitter includes in a response.

Note that Twitter has renamed the rate limit headers in API 1.1 to use
“rate-limit” instead of API 1.0's “ratelimit”.

Not all headers returned by Twitter are included by default. You can
control which headers are accessible with the response_headers attribute on
the Client. By default, the important rate limit headers are returned.
Please note that all header values will be Strings so you'll need to
convert rate limits, etc to ints in your code.

Dealing with Errors

If the request to Twitter does not return a status code of 200, then a
TwitterError is thrown. This contains the HTTP method used, the full
request URI, the response status, the response body in text and a response
object build by parsing the formatted error returned by Twitter. It's
a good idea to wrap your API calls with rescue clauses for
Grackle::TwitterError.

If there is an unexpected connection error or Twitter returns data in the
wrong format (which it can do), you'll still get a TwitterError.

Formats

Twitter allows you to request data in particular formats. Grackle
automatically parses JSON and XML formatted responses and returns an
OpenStruct. The Grackle::Client has a default_format you can specify. By
default, the default_format is :json. If you don't include a named
format in your method chain as described above, but use a “?” or “!” then
the Grackle::Client.default_format is used.

If you specify a format that Grackle doesn't parse for you, you'll
receive a string containing the raw response body. If you want to receive
the raw response body even for XML or JSON formatted responses, tell the
Grackle client to use the StringHandler handler. For example, the
following code sets the Grackle client to return JSON instead of an
OpenStruct:

DEPRECATION NOTICE: As to Twitter API 1.1, XML is no longer an accepted
format.

Odds and Ends

If you need to append something to the request path that isn't a valid
ruby method, e.g.

/1user/lists.json #1user isn't a valid Ruby method

you can use the Grackle::Client#_ method like so:

client._('1user').lists.json

REQUIREMENTS

You'll need the following gems to use all features of Grackle:

json

oauth

mime-types

Ruby Version Support

Grackle is tested on 1.8.6, 1.8.7, 1.9.2 and 1.9.3.

If you are using 1.8.6, please be aware that certain newer versions of the
json and oauth gems are not compatible with that Ruby version. You can use
older version and grackle will work fine. On 1.8.6, I recommend using oauth
0.4.4 and json < 1.7.

INSTALL

Grackle is available on rubygems.org. Just do the usual:

gem install grackle

LICENSE

Permission is hereby granted, free of charge, to any person obtaining a
copy of this software and associated documentation files (the
'Software'), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to permit
persons to whom the Software is furnished to do so, subject to the
following conditions:

The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN
NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
USE OR OTHER DEALINGS IN THE SOFTWARE.