README.md in sucker-1.3.1 vs README.md in sucker-1.4.0

@@ -8,49 +8,92 @@
 ![Hoover](https://github.com/papercavalier/sucker/raw/master/hoover.jpg)
 
 Usage
 -----
 
+Read the [API](http://aws.amazon.com/archives/Product%20Advertising%20API). Jump to the __Operations__ section if in a hurry.
+
 Set up.
 
-    worker = Sucker.new(
+    worker = Sucker.new \
       :locale => :us,
-      :key    => 'API KEY',
-      :secret => 'API SECRET')
+      :key    => api_key,
+      :secret => api_secret
 
 Build a request.
 
     worker << {
       'Operation'     => 'ItemLookup',
       'IdType'        => 'ASIN',
-      'ItemId'        => '0816614024',
+      'ItemId'        => 10.asins,
       'ResponseGroup' => 'ItemAttributes' }
 
 Get a response.
 
     response = worker.get
 
-Do something with it.
+Fulfill a business value.
 
-    items = response['Item'] if response.valid? # and so on
+    if response.valid?
+      response.each('Item') do |item|
+        consume item
+      end
+    end
 
 Repeat ad infinitum.
 
+The following are all valid ways to query a response:
+
+    items = response.find('Item')
+    items = response['Item']
+    items = response.map('Item') { |item| ... }
+    response.each('Item') { |item| ... }
+
+To dig further into the response object:
+
+    p response.valid?,
+      response.body,
+      response.code,
+      response.errors,
+      response.has_errors?,
+      response.to_hash,
+      response.xml
+
 Read further [here](http://rdoc.info/github/papercavalier/sucker/master/frames) and [here](http://relishapp.com/papercavalier/sucker).
 
-Multiple IPs
-------------
+API Usage
+---------
 
-Amazon limits calls to a venue to one per second per IP address.
+I have a growing cottage industry of gems we use to manage our
+consumption of the Amazon API.
 
-If your server has multiple local interfaces, use them simultaneously like so:
+* [Multiplex](http://github.com/papercavalier/multiplex) binds a request
+  to a specified local IP.
+* [Throttler](http://github.com/papercavalier/throttler) throttles
+  requests to a venue to one per second per IP.
 
-    your_ips.each do |ip|
+
+A hypothetical setup:
+
+    require 'multiplex'
+    require 'throttler'
+
+    ips.each do |ip|
       Thread.new do
-        worker.local_ip = ip
-        worker.get
+        scope = "#{ip}-#{locale}"
+        Throttler.throttle(scope) do
+          Net::HTTP.bind ip do
+            # Set up worker
+            response = worker.get
+            # Consume response
+          end
+        end
       end
     end
+
+We prefer to use [Resque](http://github.com/defunkt/resque) to manage
+multiple requests. Generally, four or five workers per venue per IP
+should provide optimum throughput.
 
 Stubbing in Tests
 -----------------
 
 Use [VCR](http://github.com/myronmarston/vcr).