Getting Started Guide: SOAP Basics

Introduction

SOAP is an XML messaging technology that enables webservice requests and responses to be made over any network transport protocol, typically HTTP. Each SOAP message, either a request or response, is an XML document that consists of an Envelope element, which in turn contains a Header element and a Body element.

The envelope defines the XML namespaces for SOAP and EWS. The Header element contains metadata about the message such as authentication, transaction, or quota information.

Note: The Header element is optional in the SOAP 1.1 specification; however, EWS includes it in both the request and the response.

The Body element contains the actual content of the request or the response.

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:wsse="http://schemas.xmlsoap.org/ws/2002/07/secext"
xmlns="http://marketing.ews.yahooapis.com/V5">
  <SOAP-ENV:Header>
    ...
  </SOAP-ENV:Header>
  <SOAP-ENV:Body>
    ...
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

For EWS, all SOAP messages are in SOAP 1.1 document-literal or wrapped format. Requests are sent to a secure EWS web server (HTTPS) using the POST method. The EWS server processes the request and returns a response.

See EWS Requests and EWS Responses for more information about SOAP and EWS.

See Simple Object Access Protocol (SOAP) 1.1 for detailed information about SOAP.

XML Namespace

The EWS XML namespace is http://marketing.ews.yahooapis.com/{version}, where the value of {version} is the current major version of the product. Use this namespace in your SOAP definitions.

SOAP Toolkits

Because SOAP messages are just XML documents posted to a secure web server, you can use any software you like to write SOAP messages for EWS. However, SOAP client software can significantly ease the development process by providing a framework on top of SOAP, enabling you to make requests with just a few method calls and binding the XML data types to those within your language.

For EWS, we recommend these toolkits:

See http://www.soapware.org for other languages or software that support SOAP.

WSDL Files

SOAP web services are described using the Web Services Description Language (WSDL). WSDL files (WSDLs) look similar to the XML schema and fully describe the operations a web service can accept, the parameters for each request, and the format of the responses.

WSDLs are often used by client toolkits to enable functionality in that toolkit for building a request or handling a response. For example, a toolkit could use the WSDL to generate a template for the request, or to ensure the request has the correct number and format of parameters.

The WSDL file for Marketing API service is listed with the service description in the Marketing API Reference. Use these files with your favorite SOAP toolkit to more easily manage our web services.