What Is a WSDL?

The goal of this section is to give you enough information so that you can read and use the Product Advertising API WSDL. You typically read a WSDL to understand value types, operation definitions, and request and response formats.

A WSDL (Web Service Description Language) is an XML document that defines the operations, parameters, requests, and responses used in web service interactions. You can think of a WSDL as the contract that defines the language and grammar used by web service clients and servers. When you look at the Product Advertising API WSDL, for example, you find in it all of the Product Advertising API operation names, parameters, request and response structures.

Request Definitions

The Request Definitions segment of the WSDL defines Product Advertising API operation requests, as shown in the following WSDL snippet.

This snippet shows some of ItemSearch 's input parameters, including Actor, Artist, Availability, and AudienceRating. The element declarations specify that these parameters are valid in an ItemSearch request. Most of the parameters in this example are strings. The type of one, however, Availability, is a variation on the base class, string. In this case, the variation puts a restriction on the strings that can be valid values for Availability. For that reason, the restriction keyword is used. The restriction is that the valid values for Availability are defined by an enumeration. The enumeration, however, has only one valid value, "Available," which means that the parameter, Availability can be set to only one value.

minOccurs refers to the minimum number of times the parameter must appear in an ItemSearch request. If the value is zero, the associated parameter is optional. If the value is 1, the associated parameter is required to be included once in every request involving that operation. The default value is 1, that is, if minOccurs is not included in an element declaration, minOccurs is 1.

maxOccurs defines the maximum number of times the parameter can appear in a request. The default is 1, that is, if maxOccurs is not included in an element declaration, maxOccursis 1 and the parameter can only appear once in a request. In the preceding example, maxOccurs is "unbounded," which means that the AudienceRating parameter can appear any number of times in an ItemSearch request.

In the preceding example, the parameter types are declared to be simpleTypes. A simple type cannot have child elements or attributes. Complex types can. In practice, any parameter that can take multiple values, such as an array, must be defined as a complex type.

The following snippet shows an example of a complex type.

This definition snippet shows three of the parameters that can be part of an ItemSearchrequest.

Response Definitions

The response section defines the responses returned by default by each operation. The following snippet shows some of the specifications of an ItemSearch response.

The response section shows that an ItemSearch response contains two optional (minOccurs=0) elements, OperationRequest and Items. Both of these elements are references (ref=), which means that they are defined further down in the WSDL.

Further down in the WSDL, OperationRequest is defined, as follows

This definition also contains several references. One is Arguments, which is defined further down in the WSDL. To fully understand the definition of the parts of a request, you keep digging down through the layers of refs. You know that you have reached the end of the definition hierarchy when you no longer have "ref" in the element's definition. Instead, the element definition will have a "name," the name of the element, and "type," which specifies the element's type. The type will be a base type, such as, string, which is defined in the schema (xs:), as shown.

<xs:element name="RequestId" type="xs:string" minOccurs="0" />

This line defines RequestId to be of type string, which is defined by the W3C schema.

When you look at a sample response, shown in the following example, you can see how the definition of RequestId is carried out.

First, you see that the value for RequestId is string. Secondly, the name of the element is RequestId. Third, you can see, in the XML hierarchy, how the definition of RequestId is nested inside the OperationRequest element, which is nested inside of ItermSearchResponse. Remember, it was the "ref" keyword that created the nesting in the WSDL.

Definitions

Topics

The Definitions section of the WSDL defines the namespaces used throughout the WSDL and the name of the service, as shown in the following snippet of the Product Advertising API WSDL.

This example shows that the:

  1. Default namespace is xmlns="http://schemas.xmlsoap.org/wsdl/"
  2. SOAP namespace used is xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
  3. Schema used is xmlns:xs="http://www.w3.org/2001/XMLSchema"
  4. Product Advertising API WSDL namespace is "http://webservices.amazon.com/AWSECommerceService/2013-08-01" The date at the end is the version number. It is the date the WSDL became public.
  5. TargetNamespace is "http://webservices.amazon.com/AWSECommerceService/2013-08-01" The TargetNamespace is an XML schema convention that enables the WSDL to refer to itself (as the target). The TargetNamespace value is the Product Advertising API WSDL namespace

Namespaces

Namespaces are collections of parameters and operations in which their names are unique. The advantage of using namespaces is that the WSDL can define terms, like string, just by referring it its namespace, xs. Also, prepending the namespace to a parameter ensures that there is no danger of name collisions.

Each namespace declaration starts with "xmlns:" (XML namespace:) and is followed by the abbreviation for the namespace. For example, in the following namespace declaration, xs becomes the abbreviation for the URL of the schema.

xmlns:xs="http://www.w3.org/2001/XMLSchema" 

Throughout the remainder of the WSDL you will see parameters defined in terms of namespace abbreviations, for example:

type="xs:string"
ref="tns:HTTPHeaders"

These abbreviations provide the namespace in which the parameters are defined.

Binding

The binding segment of the WSDL specifies how operation requests and responses, defined in PortType, are transmitted over the wire using underlying transport protocols.

Binding values include HTTP GET, HTTP POST, and SOAP. SOAP is not tied to a specific transport. SMTP, FTP, and HTTP are options that can transport a SOAP request; however, HTTP is the most common. Note

The Product Advertising API does not support HTTP POST requests for these cart operations: CartAdd, CartClear, CartCreate, CartGet, and CartModify. Use an HTTP GET request for these operations instead.

This binding shows that Product Advertising API uses two SOAP extensions: soap:operation and soap:body.

The soap:operation element specifies that the Product Advertising API operation,ItemSearch , in this case, is bound to a specific SOAP implementation. The soapAction attribute specifies that the SOAPAction HTTP header is used to identify the Product Advertising API service, which is the URI value of soapAction, http://soap.shopping.com. soapAction enables web servers to determine the intent of the SOAP request without having to examine the message portion of the SOAP payload. Specifying this URI is required to access Product Advertising API web servers.

The soap:body element specifies the input and output details. The value in the Product Advertising API WSDL is "literal," which means that instead of encoding the input and output as a SOAP struct, a literal XML document is used. You have seen that Product Advertising API responses are XML documents.

Service

The Service segment of the WSDL specifies the web service used, which, in this case, is Product Advertising API, as shown in the following WSDL snippet:

This information changes very rarely and so you need not pay much attention to it.

Every Product Advertising API request includes this service declaration, as shown in the following example.