The AdWords API Web Services use document-style versions of the simple object access protocol (SOAP). A client program sends a SOAP request; the web service processes the request and sends a response. Both the request and the response are packaged as XML messages that have a header and a body.

For the AdWords API, all API messages are sent via HTTPS requests. The XML for the SOAP request is sent as an HTTP POST request with a special SOAPAction header; the response is sent back as the response to the POST. All AdWords API calls are encrypted with SSL (that is, as HTTPS) to protect the privacy of your data.

The header describes meta data about the message. In the case of the AdWords API Web Services, the header must include the email and password for logging in to the AdWords account. The header must also include a useragent string that identifies the client company and a token string containing your developer token. The body of the message specifies the requested operation (such as addAdGroup) along with any applicable parameters (such as the data for the new Ad Group).

The requests that a web service can process are defined in a web services definition language (WSDL) file in XML. The WSDL file describes the operations that the web service can perform, the required parameters for each operation, and the response for each operation.

Typically, to use the AdWords API Web Services, you would download a toolkit that knows how to interpret WSDL files and how to encode and decode XML request and response messages. When an AdWords API Web Service receives a request, it sends back the response as an XML message. The web service toolkits know how to parse the response and return a data structure or object back to the caller, as appropriate for the language.

The exact toolkit you would use depends on the language you are using. Some toolkits do more for you or work better than others. Some take care of all the XML for you; others require you to write some XML yourself. The commonly used toolkits include:

• Java: Apache Axis. We have tested against 1.2 RC2, which you can get at archive.apache.org.
  
  
• Windows: Visual Studio .NET 1.1
  
  
• Perl: SOAP::Lite 0.65
  
  
• PHP: Pear and NuSOAP. Note that Pear generates rpc-encoded XML whereas NuSOAP can be made to generate document/literal XML.
  
  
• SOAPpy
  

Note: The AdWords API uses document/literal style SOAP, not rpc/encoded style. Some toolkits work differently for document-style web services than for rpc-style. If you use a SOAP toolkit, you should rarely have to write XML code to use the AdWords API Web Services, since the toolkits handle the XML generation. Some toolkits, however, may require you to hand-code some of the XML yourself. For example, nusoap.php, requires you to write the XML code for input parameters. It can sometimes be helpful to capture the XML request and response messages for debugging purposes. See the FAQ on the AdWords API Developer web site for details of how to capture XML for a variety of toollkits.

To learn more about SOAP, see the SOAP Tutorial at W3Schools: http://www.w3schools.com/soap/default.asp