Login

Using Amazon Web Services With PHP And SOAP (part 1)

It’s the coolest store on the Web – and now, its databases are accessible to you. Welcome to Amazon Web Services, an XML-based API that allows you to quickly build an online store that leverages off Amazon.com’s massive databases. Find out more, inside.Everyone, but everyone, knows what Amazon.com is – it’s the largest (and, for my
money, coolest) online store on the planet, selling everything from baby clothes
to the new Volkswagen Beetle. It’s been around since the beginning of the Web
and offers one of the friendliest shopping experiences online, together with
great customer service and a wide variety of discounts.

One of the
reasons for Amazon’s dominance in the online shopping space is its creativity –
the store’s managers are constantly coming up with innovative new ideas to
simplify and enhance the customer experience. And one of the cooler new ideas to
emerge from Amazon HQ in recent months has been Amazon Web Services, a set of
APIs designed to let users query the complete Amazon database using a series of
SOAP-based remote procedure calls. These Web services allow regular users to
easily create online stores that leverage off Amazon’s experience (and huge
product catalog), and to build cutting-edge e-commerce applications quickly and
efficiently.

Now, your favourite language and mine, PHP, has recently
started shipping with support for XML-based remote procedure calls (including
SOAP) over HTTP. This makes PHP ideal for developers looking to integrate Amazon
Web Services into their Web applications. The only problem? Not too many people
know how to do it.

That’s where this tutorial comes in. Over the next few
pages, I’ll be demonstrating how you can use PHP, in combination with Amazon Web
Services, to add powerful new capabilities to your Web applications. Take a
look.{mospagebreak title=Remote Control} Before we get into the code, though,
you need to have a clear understanding of how Amazon Web Services, aka AWS,
works. This involves getting up close and personal with a complicated little
critter known as SOAP, the Simple Object Access Protocol.

According to
the primer available on the W3C’s site (http://www.w3.org/2002/ws/), SOAP is a
“lightweight protocol for exchange of information in a decentralized,
distributed environment. It is an XML based protocol at the core of which is an
envelope that defines a framework for describing what is in a message and how to
process it and a transport binding framework for exchanging messages using an
underlying protocol.”

If you’re anything like me, that probably made
very little sense to you. So here’s the Reader’s Digest version, which is far
more cogent: “SOAP is a simple XML based protocol to let applications exchange
information over HTTP.” (http://www.w3schools.com/soap/soap_intro.asp)

SOAP
is a client-server paradigm which builds on existing Internet technologies to
simplify the task of invoking procedures and accessing objects across a network.
It uses XML to encode procedure invocations (and decode procedure responses)
into a package suitable for transmission across a network, and HTTP to actually
perform the transmission.

At one end of the connection, a SOAP server
receives SOAP requests containing procedure calls, decodes them, invokes the
function and packages the response into a SOAP packet suitable for
retransmission back to the requesting client. The client can then decode the
response and use the results of the procedure invocation in whatever manner it
chooses. The entire process is fairly streamlined and, because of its reliance
on existing standards, relatively easy to understand and use.

Here’s a
quick example of what a SOAP request for the procedure getFlavourOfTheDay()
might look like:

I’m not going to get into the details of how SOAP works in
this article, preferring instead to focus on how SOAP can be exploited in the
context of PHP and AWS. If you’re new to SOAP, the information above should be
sufficient to explain the basic concepts and ensure that you can follow the
material that comes next; however, if you’re interested in learning more about
SOAP (or if you just have trouble falling asleep at night), you should read the
W3C’s specifications on the protocol – links will be included at the end of this
article.{mospagebreak title=The Bare Necessities} here are a couple of things
you’ll need before you can get started with PHP and AWS. Obviously, you need a
working build of PHP – I recommend the latest version, PHP 4.2.3, which you can
download from http://www.php.net/

You’ll also need an
external PHP class named NuSOAP, which exposes a number of methods that can be
used to instantiate a SOAP client and perform SOAP transactions over HTTP. You
can download NuSOAP from http://dietrich.ganx4.com/.

Finally, you need a ticket to the Amazon.com gravy train. Drop by http://www.amazon.com/webservices/,
register with Amazon.com, and pick up your free developer token. This developer
token will be used in all your interaction with AWS, so handle it carefully –
you’re going to need it very soon.

While you’re on the Amazon.com Web
site, you might also want to download the AWS software development kit, which
contains numerous examples of how AWS can be used on different platforms,
together with detailed documentation of the AWS API. Be sure to read the SOAP
development guidelines in the AWS documentation, so that you don’t inadvertently
burn down Amazon’s servers.

All set up? Let’s rock and roll.{mospagebreak title=Anatomy Class} Amazon has made a number of important method calls
available in the AWS API – here’s a brief list:

BrowseNodeSearchRequest()
– retrieve a list of catalog items attached to a particular node in the Amazon
database;

ASINSearchRequest() – retrieve detailed information for a given
product code;

KeywordSearchRequest() – perform a keyword search on the
Amazon database;

The first order of business is to include the SOAP class
which contains all the methods needed to access SOAP services.

Now, in this SOAP universe, Amazon provides the SOAP server,
and this PHP script works as the client. So, the next step is to instantiate
this client, using the class constructs provided by NuSOAP.

<?php
// create a instance of the SOAP client object
// remember that this script is the client,
// accessing the web service provided by Amazon.com
$soapclient = new
soapclient(“http://soap.amazon.com/schemas2/AmazonWebServices.wsdl”,
true); ?>

The class constructor accepts a single parameter, which is
the URL of the SOAP service to be accessed (this is sometimes referred to by
geeks as the “endpoint”). In case you’re wondering where I got this URL from –
it’s listed in the AWS documentation. So there!

In order to simplify
usage of the AWS API, I’ve created a “proxy client”, one which lets me directly
invoke AWS methods, rather than passing them to the NuSOAP class’ call() method.

In this case, I’m calling the BrowseNodeSearchRequest()
method on the AWS SOAP server, and passing it a list of arguments (this argument
list is also documented in the AWS API). This argument list is stored in the
$params array, which looks like this:

1. The “browse_node”
argument specifies the node to begin with in the catalog. This node ID can be
obtained by visiting the Amazon.com Web site and looking at the URL for the
section you’re interested in browsing. For example, the URL

http://www.amazon.com/exec/obidos/tg/browse/-/18

points to the Mystery category in Amazon’s bookstore and has
node ID 18.

In case this seems like too much work, a list of the most
popular node IDs is available in the AWS documentation.

2. The “page”
argument specifies the page offset to display. AWS is currently hard-wired to
display 10 items per page, so if you wanted to display items 11-20, you would
need to set

‘page’ => 2

and so on.

3. The “mode” argument specifies the
particular store to browse. As of this writing, AWS defines 16 stores, each with
a unique “mode” identifier – here’s a list of the ones I visit most often:

Books:
‘mode’ => ‘books’” Toys:

Again,
a complete list of stores is available in the AWS documentation.

4. The
“tag” argument specifies your Amazon.com Associates ID, if you have one. In case
you don’t, and if you’re serious about building an online store with AWS, I
suggest you get one post-haste from http://associates.amazon.com/, since it
entitles you to a commission on every purchase made via your site.

5.
The “type” argument specifies the type of result set you would like. AWS gives
you two choices – “lite”, which contains basic product information, and “heavy”,
which contains detailed product information. I’ll show you both in this
article.

6. Finally, remember that developer token you got when you first
registered for AWS? You need to specify it via the “devtag” argument in order to
use AWS; if it isn’t included in the argument list, AWS will deny you access.

If you take a look at the internals of the SOAP class, you’ll see that
the proxy uses the class’ call() method and the arguments passed to it to
generate a SOAP request, which looks something like this:

Obviously, this is not very useful – but we’re just getting
started. Flip the page, and I’ll show you how to massage all this raw data into
something a little less ugly.{mospagebreak title=The Bookworm Turns} If you take
a close look at the output of the previous example, you’ll see that the call to
BrowseNodeSearchRequest() results in a PHP associative array containing a series
of result elements. It’s extremely simple to convert the raw data contained
within this array into a properly-formatted HTML page. Watch!

There’s no magic here – all I’ve done is taken the
associative array created by NuSOAP from the SOAP response and massaged its
elements into a properly-laid out Web page. Most of the work happens in the
“foreach” loop, which iterates through the result array and displays the items
in a table, complete with thumbnail images.

In case you’re wondering
where all the data came from, flip back to the previous page and look at the
keys of the associative array generated by NuSOAP – you’ll see that the name of
each key is self-explanatory, and maps into the data displayed on the page
above. Notice also that each item is accompanied by a link to the product
information page on the actual Amazon.com Web site, and that this URL (obtained
from the “Url” key of the result array) also contains an embedded Associates ID
so that Amazon can send you a commission in case the click results in an actual
sale.

In the event that the procedure generates an error on the server,
the response array will contain a SOAP fault. It’s generally considered good
programming practice to check for this and handle it appropriately – you’ll see
that I’ve done this in the script above.{mospagebreak title=Sorting Things Out}
Now, the list displayed on the previous page is sorted in the default order
imposed by Amazon.com. However, AWS allow you to alter this sort order by
specifying an optional “sort” argument in the call to BrowseNodeSearchRequest().
This “sort” argument allows you to sort products by price, by sales rank, by
rating, by date or alphabetically.

In order to demonstrate this, consider
the following enhancement to the example on the previous page, which performs
three BrowseNodeSearchRequest() calls, each one applying a different sort
criteria. The first one displays items in the default order; the second displays
featured items first; and the third displays items by sales rank. Notice how the
results of these three AWS calls can be massaged to create a more dynamic,
informative and user-friendly page.

In this case, the additional “sort” argument is used to
obtain a list of featured items and bestsellers within the Mystery node of the
Amazon book database. Here’s what the output looks like:

A number of other sort criteria are available in AWS –
take a look at the documentation for details.{mospagebreak title=Turning The Pages} You’ll remember, from my explanation of the various arguments to
BrowseNodeSearchRequest() a few pages back, that AWS returns search results in
chunks of ten, and the “page” argument must be used to obtain subsequent pages
of the result set.

Thus far, all the examples you’ve seen have been
limited to displaying ten items…not very useful in the real world at all.
That’s why this next example adds previous and next page links to assist in
navigating between the different pages of the result set.

How does this work? It’s actually pretty simple – first, the
total number of items in the result set is obtained from the SOAP response and
assigned to a variable; this number is then divided by ten and rounded up to
obtain the total number of pages to be displayed. Then, previous and next page
links are added to the bottom of the page – each link calls the same script
again and passes it a new page number via the GET method. This page number is
then incorporated into the call to BrowseNodeSearchRequest(), and a new data set
is obtained and displayed.

Here’s what it looks like:

One caveat, though: AWS 2.0 contains a bug that
sometimes causes it to display an incorrect number of total results. Hopefully,
this will be fixed in an upcoming release – until then, be warned.{mospagebreak title=Weapon Of Choice} In addition to the BrowseNodeSearchRequest() call, which
is kinda like a shotgun, AWS also allows you to laser in on a specific item via
the ASINSearchRequest() method, which accepts an ASIN – Amazon’s unique code for
each product – and returns information on the corresponding item. Consider the
following example, which demonstrates:

Note the difference in the arguments passed to the method
call – instead of a “browse_node” argument, this method used the “asin”
argument, which specifies the ASIN to search for. This ASIN must be provided to
the script above via the URL GET method, like this:

if you are a serious developer, i would recommend
buying both books – i refer to both the wrox book and this one since
neither one is exhaustive – but i learnt more from this one, as it is
written in a clearer manner.
)
[1] => Array
(
[Rating] => 2
[Summary] => A questionable
book…
[Comment] => After all the
flaky reviews this book has received, I was unsure if I was reading
individual marketing campaigns sponsored by the various publishers or
actual reviews. It seems that people cannot simply agree that this book
is good or is bad as there is just nothing in between. Even in all the
review cases, many people didn’t find the reviews helpful, both positive
and negative. It all seems complex from the consumer’s perspective when
deciding to buy this book.

So given all these statements, I thought
I’d present a true review – one from an actual reader rather than from
someone else. I think it’s pretty safe to assume that this book is good
for some people and bad for others. The problem is that the reviews
already here have so much fluff that they didn’t even begin to describe
themselves, thus they could be ambitious or lazy, smart or dim, and
hobbyist or entrepreneurs. There is simply no way of telling.

Personally, I think many of these concepts can be learned in PHP in
about 2-3 days of trying the APIs out if you already know a great deal
of XML. So if I’m going to buy a book on PHP and XML, I expect that it
will provided added value information as well as design decisions,
business concerns and best practices. Examples are not what I care about
as much as the rich and deep information because there are many examples
already on the web – no point acquiring the book just for those alone.
That makes me question the reviewers who say the examples are clear and
concise – the examples on the web already do that. Books are supposed to
provide added value to these APIs and examples to make the topic
complete and valuable to the reader. The book should also scale well to
both beginning audiences (this book does very well) to expert audiences
that want to drill through the basic information like APIs and examples
and learn more advanced techniques, best practices, etc. This book
doesn’t deliver on these areas very well unfortunately.

So, for a
person like me: This book receives 2 stars. I didn’t learn all that much
from it and I was disappointed to say the least. He’s a good writer,
funny at times, and knows what he is doing, but he also catered to a
specific audience and it shows. Is that the goal? Probably. But I think
the expert people shouldn’t have expected too much (as I did) – that’s
the truth.

Although I personally give this book 2 stars, I believe
that many beginner PHP programmers who have a little idea to what XML is
will benefit from it. If you’ve already read some XML material on the
net and even read a book or two, this book won’t exactly help you out
too much. However, this segment is rather small I would believe. I’m
still looking for a book that I can give to my employees for reference
as well as added value information. When I find it, I’ll put a review
there as well so you can compare.

So there you have it – an honest
review. I hope it helps people out in their purchasing decisions.
)
[2] => Array
(
[Rating] => 4
[Summary] => One of the best
XML and PHP titles
[Comment] => Most XML books
suffer from painful verbosity. Useful information on a relatively simple
subject tends to be hidden in drifts of useless cruft.

This book
focuses on the core information needed to become competent using XML and
PHP together. While it is not the most comprehensive reference on XML
available, it is the first resource that I check.

Wondering how I got so much extra data this time? That’s
because I told AWS I wanted the “heavy” form of the data, not the “lite” one
I’ve been using thus far.

In case you’re curious, yes, I’ve used the
sprintf() function call to reformat the ASIN to a ten-character zero-padded
string. This is because AWS will return an error if the ASIN passed to it in a
method call is less than ten characters in length.{mospagebreak title=Hooking Up} The ASINSearchRequest() method, combined with the AWS “heavy” data format,
makes it easy to build detailed product information pages that are similar to
the originals on Amazon.com. Consider the following revision to the example on
the previous page, which accepts an ASIN on the URL and returns a
neatly-formatted product information page:

Now here’s something for you
to think about. Remember how, a few pages back, I built a product catalog with
the BrowseNodeSearchRequest() method and linked each item in that catalog to the
actual product page on Amazon.com? Well, with the ASINSearchRequest() method,
you no longer need to link to Amazon.com for detailed product information – you
can generate it yourself! Simply alter the links in the product catalog to point
to the PHP script above, send the script the ASIN via the GET method, and you
can provide your visitors with detailed product information on your own
site.

I’ll leave this last to you as an exercise. Give it a shot, and
come back next week for the second part of this article, when I’ll be showing
you how to add search capabilities to your rapidly-evolving online store. See
you then!

Note: All examples in this article have been tested on
Linux/i586 with Apache 1.3.24, PHP 4.2.3, NuSOAP 6.3 and AWS 2.0. Examples are
illustrative only, and are not meant for a production environment. Melonfire
provides no warranties or support for the source code described in this article.
All product data in this article belongs to Amazon.com. YMMV!