$Id: NOTES,v 1.4 2008/03/27 17:57:44 ianmacd Exp $

Previous versions of Ruby/Amazon were built around version 3.x of the Amazon
Web Service API. When that API was current, it was known by the name AWS 3.x.

Amazon later renamed AWS to ECS, or E-Commerce Service, for the launch of
version 4 of the API.

Demonstrating the wisdom for which large companies are famous, Amazon changed
its mind once again in 2007, reverting to the familar name of AWS; only now,
it stands for Associates Web Service.

Since Amazon started offering AWS, the number of Amazon Web APIs has grown. It
is therefore no longer appropriate to call this library Ruby/Amazon, because
it confines itself to the AWS API. Henceforth, this library shall be known as
Ruby/AWS.

Ruby/AWS is built around version 4 of the Amazon AWS API, which is
fundamentally different to version 3, both in terms of how data is requested
and returned. The underlying XML data structures are radically changed from
previous versions.

It has therefore not been possible in Ruby/AWS to retain any level of API
compatibility with Ruby/Amazon. In any case, the vast majority of the
functionality in Ruby/Amazon will soon cease to be of use, because servicing
of calls to version 3.x of the AWS API will be discontinued by Amazon as of
2008-03-31. This is mere days away as I write this.

Unfortunately, this means that any code written for Ruby/Amazon will need to
be rewritten to work with Ruby/AWS.

Things are a tad worse than that, however.

Ruby/AWS is currently alpha code. Amongst other things, this means:

- You will probably encounter _many_ bugs. You will certainly encounter some.

- The documentation is scant. By that, I mean that you're reading most of it
  right now.

- Not all features are currently implemented. This applies to both features
  making their debut in version 4 of the AWS API (such as multiple operation
  requests), as well as features that _were_ previously implemented in
  Ruby/Amazon, such as shopping carts.

  If you need to use Amazon shopping carts from Ruby, you will need to look
  elsewhere for the time being.

  On the bright side, currently implemented operations are:

    ItemSearch
    ItemLookup
    SellerListingSearch
    ListSearch
    BrowseNodeLookup

- Classes, methods, constants and instance variables may change name in the
  future. Data structures and objects may change shape, grow, shrink or
  disappear entirely.

In short, code written to work with this release of Ruby/AWS may stop working
when you upgrade to the next release. In fact, it may even stop working
_during_ this release, because it's very likely there are circumstances that
would cause an exception to be raised, that I haven't come across in my
limited testing of the code.

The majority of the programming in Ruby/AWS was performed in accordance with
the spec for the 2007-07-16 revision of the AWS API:

  http://docs.amazonwebservices.com/AWSECommerceService/2007-07-16/DG/

However, I have now started to use the 2008-03-03 revision of the spec:

  http://docs.amazonwebservices.com/AWSECommerceService/2008-03-03/DG/

One mildly good bit of news is that /etc/amazonrc and ~/.amazonrc used with
previous versions _are_ compatible with Ruby/AWS. The only change required for
AWS v4 is the addition of a 'key_id' parameter, which should contain your AWS
Access Key ID.

You can obtain an AWS Access Key ID here:

  https://aws-portal.amazon.com/gp/aws/developer/registration/index.html

Subscription IDs are deprecated by Amazon and, in any case, not supported by
Ruby/AWS. Please obtain and use an AWS Access Key ID instead.

Although there is currently no support for multiple operation requests, batch
requests are supported. Watch out for bugs, though.

There are many combinations of parameters and values that are legal for a
particular type of search. For example, an ItemSearch can use a Sort parameter
with a value of 'titlerank' if the SearchIndex is 'Books'. However, this value
wouldn't make much sense in the 'Automotive' SearchIndex.

The very presence of a certain parameter can be illegal in a certain contexts.
For example, specifying the parameter 'Author' with any value would be
nonsensical in the 'PetSupplies' SearchIndex.

To complicate things further, the validity of parameters and their values
differs not only by search type, but also by Amazon locale (amazon.com,
amazon.co.uk, amazon.de, etc.) and is prone to change with each minor revision
of the Amazon AWS API.

Ruby/Amazon attempted to track these complex and dynamic relationships to
prevent illegal or ineffective operations from being attempted. It was a
time-consuming and tedious task to track the evolving API (which often changed
in subtle ways without prior notice from Amazon), find all of the corner cases
and handle undocumented relationships.

With the highly dynamic nature of the Amazon environment and the AWS API, plus
the sheer size of the current API, this strict approach has now become
impractical. It's therefore now up to you to ensure that you pass in sensible
parameters and values for the type of operation you're performing and the
locale in which you're working.

Parameter name checking, however, _is_ still carried out. For example,
performing an ItemSearch and passing in a 'Keywrds' parameter would generate
an exception, because 'Keywrds' doesn't exist as a parameter in any context.
Here, 'Keywords' was obviously intended and a simple typo was made by the
user.

Similarly, the SearchIndex must also actually exist, so 'Music' or 'Beauty'
would be valid, but 'Furniture' or 'MobilePhones' would not, because Amazon
does not (currently) offer them.

In conclusion, we can say that broad checks are performed to determine whether
a search _could_ conceivably be valid in a certain context, but it's up to you
to determine whether the search actually _is_ valid in your particular
context.

Thankfully, with the AWS Developer Guide at your side, it's mostly common
sense which parameters and values can be used with each type of search. It's
less obvious when these differ by locale, such as 'Beauty' being a valid
SearchIndex in the 'us' locale, bot not in the 'uk'.

The only way to apprise yourself of such quirks is to read Amazon's latest
developer documentation (and closely follow the release notes of each minor
API revision to make sure things haven't changed).

For those illegal operations that make it through and are passed to the Amazon
servers, the good news is that Amazon carries out extensive request-time
parameter checking in AWS v4 (much better than in v3) and will generate an
error when an illegal set of parameters and values is given. Ruby/AWS will
dynamically generate an exception class for the reported type of error and
raise an exception of that class.

Using this approach, Ruby/AWS doesn't have to perform checks that Amazon will
perform anyway. This helps keep the code base leaner, the library faster, and
reduces the chances of Ruby/AWS disallowing operations that will one day be
allowed in a minor revision of AWS.
