Amazon E-Commerce Service (Amazon ECS) released a major update to its web service API in October 2004. As part of the release, the name was formally changed from Amazon Web Services 3.0 to Amazon E-Commerce Service 4.0, or just Amazon ECS, as Amazon ECS is now one of the many web services offered by Amazon Web Services.

To help keep the confusion to a minimum, we’ll use ECS 3.0 to refer to the older software product and we’ll use ECS 4.0 to refer to the latest Amazon ECS product made available in October 2004.

The goal of this guide is to ease your migration from ECS 3.0 to ECS 4.0. This guide highlights the major differences between the software releases and shows you how to recreate the same functionality using ECS 4.0. While this guide provides a basic introduction to ECS 4.0 concepts, you should refer to the Amazon ECS technical documentation for more details.

We’ve included links to specific topics in the documentation throughout this guide, so keep a look out for those tips. There are links to other useful resources at the end of this guide to help with your migration. There's also a more in-depth and printable version of this migration guide attached below.

Why Migrate to ECS 4.0?

Moving to ECS 4.0 has a number of benefits over ECS 3.0:

• Improved data breadth and quality
  ECS 4.0 provides access to additional data through an expanded set of response groups, operations and parameters. Examples include TopSellers and NewReleases for browse nodes, access to Wedding and Baby registries, and more powerful searching capabilities. In addition, data accuracy and quality has been improved in ECS 4.0.
• Extended capabilities
  The features and capabilities of ECS 4.0 have been greatly improved. New operations such as BrowseNodeLookup, CustomerContentLookup and ListSearch allow you to get information about the Amazon product hierarchy, find customer generated content, and search for wish lists. Such features simply don't exist in ECS3.
• Ongoing enhancements
  ECS 4.0 is fully supported and under active development by the ECS team. All new features and enhancements are only being added to ECS 4.0.

What’s New in 4.0?

There are a number of significant changes in ECS 4.0 that we'll cover in this section. Again, check out the technical documentation for more information.

Access Key IDs

In ECS 3.0, each request must contain a valid Developer Token (passed as dev-t in REST and devtag in SOAP). ECS 4.0 takes an AWS Access Key ID.

You may already have an Access Key ID. You can access your Access Key ID by going to http://aws.amazon.com, pointing to Your Web Services Account, then clicking View Access Key Identifiers. Depending on when you signed up for ECS 3.0, you may need to re-register for an AWS account, which includes an Access Key ID.

Response Groups

Perhaps the largest difference between ECS 3.0 and 4.0 is the ability to specify what information is returned in the response. In ECS 3.0, there are only 2 options lite and heavy. However, ECS 4.0 gives you much finer control over the type of data returned. This is done using response groups.

It is beneficial for you to limit the response groups used to smallest set possible. This will generate faster responses, utilize less bandwidth, and return less XML for your application to parse.

The Large and Medium response groups in ECS 4.0 provide a simplified interface for retrieving multiple response groups at once. They have been provided mainly for development and debugging purposes only. Your production applications should specify the desired response groups individually, which will improve performance and response time.

Tip: See Response Groups in the Developer Guide for information.

API Versioning

Another concept new to ECS 4.0 is API versioning. In ECS 3.0 there was no mechanism built into the API for future growth. This problem has been solved in ECS 4.0 by versioning each interface change. Versioning is done using dates, where later dates indicate higher version numbers.

Versioning enables you to code against an interface that will not change. If you specify a particular WSDL version in your request, you are guaranteed that the response will match the types defined in the WSDL. When new functionality is added to ECS, it is only added to newer WSDL versions.

For example, the 2006-09-11 release introduced several enhancements to the offer data returned by ECS. Four new elements were added to the WSDL, one of which was the AvailabilityType field. In order to retrieve this field for SOAP requests, you need to use a WSDL version of 2006-09-11 or later. To retrieve this field for REST requests, you need to specify the proper version in the Version parameter.

Tip: See WSDL and Schema Locations in the Developer Guide for more information.

Operations

The concept of operations is very similar in ECS 3.0 and ECS 4.0. However, in ECS 4.0, you’ll find that the number of operations has been dramatically reduced and that each operation is much more powerful than before.

Operations are also specified differently in ECS 4.0 than they were in ECS 3.0. In ECS 4.0, each request must specify the operation type using the Operation parameter. In addition, each operation typically has a set of other required or optional parameters affect the behavior of that operation.

We’ll cover how ECS 3.0 requests map to ECS 4.0 operations later in this guide.

Batch and Multi-Operation Requests

Batch requests and multi-operations allow you to combine multiple requests into a single call.

Tip: See Combining Operations into a Single Request in the Developer Guide for more information.

Shopping Cart Updates

To facilitate customer purchases, ECS allows you to create and manage a shopping cart of products that a customer wishes to purchase. The shopping cart is a temporary data structure that is stored at Amazon as long as it is in use. ECS 4.0 introduces a number of API changes for working with the shopping cart.

Tip: See Using the ECS Shopping Cart in the Developer Guide for more information.

Response Formats

When using REST to access ECS 3.0, you are required to use the f parameter, which specifies either that an XML response is desired or it points to the location of an external XSLT to be applied to the response before it is returned. In ECS 3.0, even when XSLT is not being used, the f parameter is required to be set to “xml.”

In ECS 4.0, f is replaced by the Style parameter which can be used to specify the location of your XSLT file. If you are not using XSLT, this parameter is not required. If you need to set the MIME content type being returned in the response, you can set the ContentType parameter (which was the ct parameter in ECS 3.0). If no ContentType is set, the default is text/xml.

Tip: See Using XSLT with ECS in the Developer Guide for more information.

Associates ID

The AssociateTag parameter in ECS 4.0 replaces the t (REST) and tag (SOAP) parameters in ECS 3.0. You must pass this parameter to receive referral commissions from the Amazon Associates program. If you do not have an Associate ID or would like to create a new one, visit http://www.amazon.com/associates.

Errors

Errors in ECS 4.0 have been designed to be much more informative than those in ECS 3.0. It is now much easier to diagnose problems with your request and determine what went wrong. Every error now contains an error code and a message describing the problem. Error codes are the same across ECS locales, however, the messages are now translated to the appropriate language. A full list of error codes and descriptions can be found in the ECS 4.0 documentation.

Tip: See Error Codes and Messages in the Developer Guide for more information.

Making Requests

Just like ECS 3.0, ECS 4.0 fully supports REST and SOAP interfaces. However, unlike ECS 3.0, you’ll find far more consistency between the two – there are no differences between parameter names and expected values in ECS 4.0.

Tip: See the Making Operation Requests topic in the Developer Guide for more general information on making requests.

WSDL and Schema Locations

Now that Amazon ECS is versioned, it is strongly recommended you include the desired API version in your requests.

Tip: See WSDL and Schema Locations in the Developer Guide for more information.

Service Endpoints

ECS 3.0 allowed you to use the locale parameter to indicate the Amazon store for which you wanted data. This parameter has been deprecated and there is no analogous option in ECS 4.0 – you simply indicate the locale by sending your request to the corresponding endpoint. For example, requests for Amazon.co.jp data should only go to the JP endpoint.

When migrating to ECS 4.0, you should update your application to use the appropriate service endpoint. Here are the proper endpoints for REST requests:

For SOAP requests, just be sure to use the correct WSDL and the requests will be sent to the proper endpoint.

Common Parameters Conversion Chart

This section covers the common parameters in ECS 3.0 requests and their counterparts in ECS 4.0.

Tip: See Common Parameters in the Developer Guide for more information:

Operations Conversion Chart

The table below shows each ECS 3.0 operation and its corresponding ECS 4.0 operation and operation parameters. Note that each 4.0 operation in the table links to the specific API reference topic on that operation in the Developer Guide. Each reference topic contains a complete list of available parameters for the operation, and an example REST request.

*Using a single ASIN, either the SimilarityLookup or ItemLookup operations can be used. See the section on “SimilarityLookup” for details.

Example REST Requests

Here are a few example REST requests that show a few basic requests to ECS 4.0.

Searching for a CD by Keyword

This request searches for products in the Music search index that contain the keywords "The Who."

http://ecs.amazonaws.com/onca/xml?Service=AWSECommerceService&
AWSAccessKeyId=0JE9C2T2RN684MDM6G02&
AssociateTag=devconn-20&
Operation=ItemSearch&
Version=2007-01-15&
SearchIndex=Music&
Keywords=The%20Who

Looking up a Particular Item

If you know the ASIN associated with a particular product, you can look up the item using the ItemLookup operation. This particular request is for information about "The Who: The Ultimate Collection," which was returned by the previous search. We've also specified that we want the item attributes and related offers as part of the response.

http://ecs.amazonaws.com/onca/xml?Service=AWSECommerceService&
AWSAccessKeyId=0JE9C2T2RN684MDM6G02&
Operation=ItemLookup&
Version=2007-01-15&
AssociateTag=devconn-20&
ItemId=B000065UFD&
ResponseGroup=ItemAttributes,Offers

Getting Help with the Migration

In addition to this guide, a few places to get information to help with the migration process are:

• Resource Center—This section of the AWS Developer Connection site includes code samples, technical documentation, and other resources for building applications on Amazon ECS.
  http://developer.amazonwebservices.com/ecs/resources
• Amazon ECS Developer Guide—Located in the Resource Center, the Developer Guide is a complete reference for how to use Amazon ECS. Here’s a link to the Developer Guide for the latest API version at the time of this writing:
  http://developer.amazonwebservices.com/connect/entry.jspa?externalID=614&categoryID=19
• Forums—If, after reading this guide and looking through the Resource Center, you have more questions, please post them to the Amazon ECS Forum:
  http://developer.amazonwebservices.com/ecs/forums