You might not realize it if you use our client libraries, but at its core the AdWords API is based on SOAP and XML. Crafting a request by hand can be tricky, and even some SOAP toolkits have problems serializing to the correct format. In version v201109 of the API we enabled additional XML validation so that you will now be alerted to structural issues with your requests.

The format of the request’s XML payload is specified by an XML Schema definition (XSD) embedded in the WSDL document for the service. The schema describes very precisely the types and elements that can appear in the request. In past versions of the API the server was somewhat lenient in how it processed the incoming XML. For example, it would silently ignore unknown elements. This had the potential to hide problems with your code or cause mysterious behavior.

With enhanced XML validation enabled, the aforementioned errors can be caught earlier, as the request payload must fully match the format in the schema. Below is a sample request and response showing a validation error for an unknown element.

Request

<?xml version="1.0"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
  <soapenv:Header>
    <RequestHeader 
      xmlns="https://adwords.google.com/api/adwords/cm/v201109">
      <applicationToken>...</applicationToken>
      <authToken>...</authToken>
      <clientCustomerId>...</clientCustomerId>
      <developerToken>...</developerToken>
      <userAgent>...</userAgent>
    </RequestHeader>
  </soapenv:Header>
  <soapenv:Body>
    <get xmlns="https://adwords.google.com/api/adwords/cm/v201109">
      <serviceSelector>
        <fields>Id</fields>
        <fields>Name</fields>
        <ordering>
          <field>Name</field>
        </ordering>
        <foo>bar</foo>
      </serviceSelector>
    </get>
  </soapenv:Body>
</soapenv:Envelope>

Response

<?xml version="1.0"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <soap:Fault>
      <faultcode>soap:Client</faultcode>
      <faultstring>
        Unmarshalling Error: cvc-complex-type.2.4.a: Invalid content 
        was found starting with element 'foo'. One of '{
         "https://adwords.google.com/api/adwords/cm/v201109":ordering, 
         "https://adwords.google.com/api/adwords/cm/v201109":paging
        }' is expected.
      </faultstring>
    </soap:Fault>
  </soap:Body>
</soap:Envelope>

In this case the response is indicating that only the elements "ordering" or "paging" are permitted in this part of the request. Please note that this error is thrown as a raw SOAP fault, and is not wrapped in an ApiError object. There is no need to add special exception handling for these errors, as they are designed to be detected and resolved during the development phase of your application. If they do occur in your production environment you should log them for later analysis.

There are some side effects of using stricter XML validation that you should be aware of:

  • The order of the elements in the request now matters. The XSD lists elements in a sequence, and the order of the elements in the request must match. That same order is reflected in the API’s reference documentation, and our client libraries ensure that it is always respected.
  • Correct element ordering is also required for ad-hoc report download requests.
  • The xsi:type attributes in a request will always be checked and the values must use the correct namespace.

This additional XML validation has been enabled in the sandbox environment for a year and half, so if your application already works there then this change should be transparent. If you have any questions about this or other aspects of the API, you can reach us on the developer forum or during office hours.

 - , AdWords API Team