Weary: The Road to 1.0
In the coming weeks, I plan on blocking out time to focus on Weary, my original Ruby pet project. Weary is the little REST consumer that powers the Tumblr Gem. I’ve written about Weary before. I have neglected it a bit since the release of tumblr-rb, but I’ve got a lot planned to get Weary to a 1.0 release. Here is what needs to be in Weary before it can reach that level:
1. Dynamic URL’s.
This is what your basic Weary Resource call looks like, taken from Tumblr::Writer:
post :delete do |del|
del.url = 'http://www.tumblr.com/api/delete'
del.requires = [:email, :password, :'post-id']
end
When you instantiate Tumblr::Writer that object now gets a method called delete:
write = Tumblr::Writer.new
write.delete :email => "test@testymcgee.com", :password => "s3cret", :'post-id' => 1234
Above, in the Resource declaration, it says that the keys :email, :password, and :'post-id' are required. When you call the delete method, if you do not provide a Hash containing all of the required keys as an argument, it will raise an exception.
The problem comes when there is a parameter that is not sent as an HTTP POST body or GET query, but as a segment of the URL. Such is the case with Tumblr’s Authenticated Reads. For a read, you must provide the username in the host of the url: http://#{username}.tumblr.com/api/read/.
The way I’ve handled this is by creating a method that falls back to Weary’s module methods:
def self.read(username, via = :get, params = {})
Weary.request("http://#{username}.tumblr.com/api/read/", via) do |req|
req.with = params unless params.blank?
end
end
This is not optimal, and makes these methods an outlier from the preferred Weary way of doing things. Weary will handle this in a future release using the Addressable gem. Wynn has been toying with this a bit, but it has yet to be merged in.
post :authenticated_read do |r|
r.url = "http://{username}.tumblr.com/api/read/"
r.with = [:start,:num,:type,:id,:filter,:tagged,:search,:state]
r.requires = [:email, :password]
end
Along with the required :email and :password keys, the Resource declaration says that a new key is required: :username, that builds the URL for the request.
reader = Tumblr::Reader.new
reader.authenticated_read :email => "test@testymcgee.com", :password => "s3cret", :username => "mwunsch"
2. Defaults at the Resource level.
Right now, it’s easy to save default key-value pairs that get sent with every request. It’s how the Tumblr Gem does a lot of its mojo. But maybe you want to have some default pairs that get sent with every resource, defined at the Class level. Weary will add a new defaults method to Resources.
post :dashboard do |dashboard|
dashboard.url = "http://www.tumblr.com/api/dashboard"
dashboard.requires = [:email,:password]
dashboard.with = [:start,:num,:type,:filter,:likes]
dashboard.defaults = {:num => 50, :likes = 1}
end
3. HTTP Connection Adapters
This is the new feature I am most excited about. Right now Weary::Request and Weary::Resource is a thin layer of syntactic sugar that sits above the standard Net::HTTP library. I’ll be working on abstracting away Net::HTTP into a Weary::Adapter class. When triggering Request#perform, it will defer to the adapter for how to form and make the Request. The Request and Resource classes will truly be abstract, and this allows us to build adapters for different HTTP libraries. So imagine doing something like this:
class Reader < Weary::Base
adapter :typhoeus
end
I’ll be working hard on defining an API for creating Adapters. Weary will default to the Net::HTTP adapter, and will come with a Typhoeus adapter. This is similar to how Faraday does it’s magic, but with the sickly sweet Weary API we’ve all come to know and love.
4. Self-documenting
This has been an intended feature of Weary for a long time, and it will be a part of moving to 1.0. Weary will hook into the YARD documentation tool, and when defining a Resource, it will generate documentation. So not only can you create a Ruby library for your API, by creating the library you are also writing documentation for your API.
Keep an eye on Weary for the next month or so as these features trickle in, inching closer to 1.0.
