I recently wrote about using ruby-aaws on Heroku. I used it for creating a virtual bookshelf on my website, so anybody interested in what I read can have a look at the ISBN, price, description and some reviews (in german). Since this is a trivial scenario it covers only a fragment of features that ruby-aaws offers.
I always felt that using ruby-aaws was way too complicated! This is how you call Amazon for the title of a book:
require "amazon"
require "amazon/aws"
require "amazon/aws/search"
il = Amazon::AWS::ItemLookup.new('ASIN', { 'ItemId'=>asin })
rg = Amazon::AWS::ResponseGroup.new('Medium')
req = Amazon::AWS::Search::Request.new
resp = req.search(il, rg)
puts resp.item_lookup_response.items[0].item.item_attributes.title.to_s
I also had to monkeypatch some stuff to get it working with Heroku the first time:
- allow .amazonrc to be on a different location that can be used on Heroku
- remove restriction to Ruby 1.8.7 and patch related Stuff
If you look into the source and documentation of ruby-aaws you will see that it is no fun to patch anything in there… I think I would not have done it without the help of Ian Macdonald.
Another thing was, that I could not use the builtin caching facility of ruby-aaws, cause it simply does not work on Heroku’s readonly file-system.
simplicity with ASIN
Given these restrictions, I decided to build a minimum featureset gem tailored for my requirements:
- provide access to the Amazon-E-Commerce-API via REST
- simple configuration points
- minimum amount of code to write for a request
- maximum flexibility
If you have a look into the Amazon documentation you see that it is quite easy to call the API via REST. Just append some query parameters to your desired endpoint (f.e. webservices.amazon.com) and as a result you get the desired information from Amazon. The tricky thing is, that since recently you have to sign your request with your AWS credentials. I did not find any specs on how to do that on the documentation, but Cloud Carpenters had a nice example using Python that I adapted for Ruby.
There is also the nice Amazon API signing service that frees you from self signing your requests. The reason I did not use it, is that it supports the amazon.com endpoint only (I need amazon.de).
requests with ASIN
Using ASIN is simple. You just have to provide your credentials to the configuration method, the rest is covered with sensible defaults that you can override if you wish:
require 'asin'
include ASIN
# use the configure method to setup your api credentials
configure :secret => 'your-secret', :key => 'your-key'
# you can override the api endpoint if you wish
configure :secret => 'your-secret', :key => 'your-key', :host => 'webservices.amazon.de'
After this setup you can call the REST api via the lookup method:
# lookup an item with the amazon standard identification number (asin)
item = lookup '1430218150'
# have a look at the title of the item
item.title
=> Learn Objective-C on the Mac (Learn Series)
# provide additional configuration options like the response group
lookup(asin, :ResponseGroup => :Medium)
Title is currently the only attribute that is directly supported from the Item class, but this is no restriction. ASIN uses Hashie::Mash for the internal data representation of the Amazon REST XML response. The Item class stores the response in a raw attribute that can be accessed for read:
# access the internal data representation (Hashie::Mash)
item.raw.ItemAttributes.ListPrice.FormattedPrice
=> $39.99
You can tailor the Item class to your needs by opening up the class and provide the methods you like or doing something entirely different with the raw attribute.
OR, just fork me on GitHub!
Maximum flexibility with some syntactic sugar!