Amazon E-Commerce Service (ECS) publishes its API through Web Services Description Language (WSDL) documents, which you can use to construct SOAP requests. ECS also provides XML schemas for validating the XML output of REST requests. WSDL documents and XML schemas are available for different versions and different locales.
The following table shows the location of the latest ECS WSDL, by locale:
The following table shows the location of the latest ECS XML schema, by locale:
Starting with Amazon E-Commerce Service (ECS) 4.0, Amazon is introducing the concept of service versioning, which allows you to specify which version of ECS you wish to use so that future enhancements and changes to ECS are not intrusive to your applications. Service versioning ensures, for example, that when Amazon adds new elements to the ECS schema, applications that validate against the current or older ECS schemas are not be affected.
The ECS service version is defined in the namespace of the ECS Web Services Description Language (WSDL) document. The WSDL namespace appears in the first line or element of the WSDL file. The following is the first element from an ECS WSDL:
<definitions xmlns="http://schemas.xmlsoap.org/wsdl/" xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:tns="http://webservices.amazon.com/AWSECommerceService/2004-08-01" targetNamespace="http://webservices.amazon.com/AWSECommerceService/2004-08-01">
The namespace of the WSDL file is the value of the attribute named targetNamespace; therefore, the namespace from the example above is http://webservices.amazon.com/AWSECommerceService/2004-08-01. The version of the WSDL is simply the date that is embedded within the namespace. In this case, the version is 2004-08-01.
ECS WSDL versions appear both in the WSDL namespace and in the URL to the WSDL file. Specifically, the URL for the WSDL used for the example above is the following:
http://webservices.amazon.com/AWSECommerceService/2004-08-01/AWSECommerceService.wsdl
Note:
If you omit the version (2004-08-01) from the WSDL URL, you receive the latest WSDL version, by default. For example, the following URL retrieves the latest WSDL for the US locale:
http://webservices.amazon.com/AWSECommerceService/AWSECommerceService.wsdl
The XML schema for REST responses is also versioned. Just as you can access specific WSDL versions by including the version number (or date) in the WSDL URL, you can also access schemas by inserting the version number in the schema URL. Here is the URL you would use to access the schema associated with the WSDL above:
http://webservices.amazon.com/AWSECommerceService/2004-08-01/AWSECommerceService.xsd
The URLs mentioned so far in this section all return the WSDL for the US locale. To retrieve the ECS WSDL for other locales, insert the locale code (US, UK, DE, or JP) after the date in the URL path. The following table shows WSDL examples for all four locales. Replace AWSECommerceService.wsdl with AWSECommerceService.xsd to retrieve the XML schema instead of the WSDL document.
Note:
If a locale code is omitted, you receive the US WSDL by default.
SOAP requests always have their namespace, which includes the version, embedded in them. To avoid problems with schema changes, be sure you build your SOAP application using a versioned WSDL, rather than the default WSDL.
For REST requests, if your application requires a specific service or schema version, you must explicitly request the version you desire by including the Version parameter in your request. Including the Version parameter ensures that ECS does not return to you response elements that your application is not designed to handle.
The Version parameter is optional. If you do not include it, your response is based on the most recent schema.
Here is an example REST request that includes the Version parameter:
http://webservices.amazon.com/onca/xml?Service=AWSECommerceService
&SubscriptionId=[your subscription ID here]
&Operation=ItemSearch &SearchIndex=DVD &Actor=Tom%20Hanks
&Version=2004-08-01