Developer Network Home - Help

Getting Started Guide: Using SOAP

SOAP is the message framework underlying the Enterprise Web Services (EWS). With SOAP you make requests and get responses using a standard XML format. You can generate and parse the SOAP XML requests and responses by hand in your client applications or, more typically, you use standard client software that supports SOAP and generates and parses the underlying XML for you.

This page provides a general overview of the SOAP technology as used by EWS. It includes these sections:

SOAP Basics

SOAP is an XML messaging technology that enables web service 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 and a Body. The Header element contains metadata about the message such as authentication, transaction or quota information; the Body element contains the actual content of the request or the response.

For EWS, all SOAP messages are in SOAP 1.1 document-literal/wrapped format. Requests are sent to a secure web server (HTTPS) using the POST method. The EWS server processes the request and returns a SOAP response. The EWS XML namespace is http://marketing.ews.yahooapis.com/V1.

The features and functions of the EWS -- that is, the operations you can request, the parameters each operation accepts, and the responses that operation returns -- are defined by the Web Services Definition Language (WSDL). The WSDL files for each of the Enterprise Web Services are listed in Web Service Description Language Files (WSDLs). Use these files with your favorite SOAP software to more easily manage our web services.

For more detailed information about SOAP, see Simple Object Access Protocol (SOAP) 1.1 Specification (www.w3.org).

SOAP Request

The SOAP request document consists of a SOAP Envelope element containing a Header element and a Body element:

<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/V1">
  <SOAP-ENV:Header>
    ...
  </SOAP-ENV:Header>
  <SOAP-ENV:Body>
    ...
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Header

The SOAP Header contains metadata about the request such as transaction identifiers or authentication information. EWS SOAP Headers contain at least four elements:

The username and password can be defined in the header in one of two ways:

For example:

<SOAP-ENV:Header>
  <wsse:Security>
    <wsse:UsernameToken>
      <wsse:Username>user</wsse:Username>
      <wsse:Password>password</wsse:Password>
    </wsse:UsernameToken>
  </wsse:Security>

  <license>abcde</license>
  <masterAccountID>12345</masterAccountID>
</SOAP-ENV:Header>

In addition, the EWS SOAP Header may contain an Account ID or second "on behalf of" username and password for users who manage accounts for others.

See Making Requests for details about about constructing SOAP request headers, authentication and authorization.

Body

The SOAP Body contains the data for the request itself, including the EWS operation name and any parameters for that operation. Parameters must be specified in order.

<SOAP-ENV:Body>
  <getCampaign>
    <campaignID>123456789</campaignID>
  </getCampaign>
</SOAP-ENV:Body>

SOAPAction HTTP Header

EWS does not require a value for the SOAPAction HTTP header. If your toolkit requires the use of this header you may leave it blank.

SOAP Response

The SOAP response document that comes back from the server also consists of a SOAP Envelope element containing a Header element and a Body element:

<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/V1">
  <SOAP-ENV:Header>
    ...
  </SOAP-ENV:Header>
  <SOAP-ENV:Body>
    ...
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Note that although the Header element is optional in the SOAP 1.1 specification EWS includes it in both the request and the response. The SOAP Header in the response contains elements for response time (how long the response took inside the web service backend) and information about the command groups and remaining quota points.

<SOAP-ENV:Header>
  <timeTakenMillis>125</timeTakenMillis>
  <remainingQuota>1000</remainingQuota>
  <commandGroup>Research</commandGroup>
</SOAP-ENV:Header>

The Body element contains the contents of the response.

<SOAP-ENV:Body>
  <Campaign>
    <ID>123456</ID>
    <advancedMatchON>true</advancedMatchON>
    <contentMatchMaxPPC>0.85</contentMatchMaxPPC>
    <contentMatchON>true</contentMatchON>
    <createDate>2006 05:30:00</createDate>
    <description>Plasma TV</description>
    <endDate />
    <lastUpdateDate />
    <name>Plasma TV</name>
    <spendAccountID>123456000</spendAccountID>
    <sponsoredSearchMaxPPC>0.85</sponsoredSearchMaxPPC>
    <sponsoredSearchON>true</sponsoredSearchON>
    <startDate />
    <status>Active</status>
    <watchON>false</watchON>
  </Campaign>
</SOAP-ENV:Body>

If there was an error or other exception during the processing of the request, the Body contains a Fault element to report the error and no other content:

<SOAP-ENV:Body>
   <SOAP-ENV:Fault>
   <faultcode>M1015</faultcode>
   <faultstring>Quota exceeded</faultstring>
   </SOAP-ENV:Fault>
</SOAP-ENV:Body>

See SOAP Faults for a list of the possible fault codes and error messages.

SOAP Client Toolkit Software

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. Some toolkits enable the use of web service definition language files (WSDLs) that define the capabilities of the language and enable you to perform operations without needing to know much about that web service ahead of time or spend a lot of time pouring over reference documentation.

This table shows the toolkits we recommend for use with EWS:

Language Toolkit
Java Apache Axis
XFire
Microsoft .Net Visual Studio .NET
Perl SOAP::Lite
PHP PHP's SOAP extension

The EWS Client Samples SDK contains commented code samples for each of these languages to perform many common operations you may want to accomplish with our web services. (Note: the Client Samples SDK is forthcoming in a future release)

For other languages or software that support SOAP, see the listings at http://www.soapware.org.

Web Service Description Language Files (WSDLs)

SOAP web services are described using the Web Service Description Language (WSDL). WSDL files look similar to XML schemata and fully describe the operations a Web service can accept, the parameters for each request, and the format of the responses. WSDL files, or just 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.

Each of the Enterprise Web Services include WSDL files for use by your SOAP software. Find these files here:

Where to go From Here

Go up to the Introduction to see the Table of Contents for the entire Getting Started Guide.

Continue on to Making Requests and Handling Responses for more detailed information on EWS requests and responses.

Copyright © 2006 Yahoo! Inc. All rights reserved.

Privacy Policy - Terms of Service - Copyright Policy - Job Openings