Launching the Google AdWords API

Nelson MinarMarch 2005

Outline

• Product overview

• SOAP, WSDL, and ReST

• Lessons from experience

Product overview

AdWords product

• AdWords: those little ads on the side of Google’s page

– Same ads also show on other sites (AdSense)

• Campaign management done via web application

– Some advertisers have many thousands of keywords!

• Hierarchical data model

– Campaign: budget, targeting options, etc

• Adgroups: CPC, enabled/paused/deleted, etc

– Keywords: text, match type, CPC

AdWords API goals

• Enable developers to integrate with the AdWords platform

• Use cases

– Technical bid management

– ROI optimization

– Keyword and campaign optimization

– Creative new user interfaces

– Integration of advertising with backend systems

• Create a third party developer community

AdWords API features

• Campaign management functions

– Keywords, Creatives, AdGroups, Campaigns, Account

• Reporting functions

• Traffic estimator functions

• SOAP + WSDL + SSL

• Quota system

• Multiple authentication mechanisms

Success stories

• Retailers managing campaign spending

– Manage CPCs to meet seasonal goals

• WebmasterWorld user testimonial

– $100 / day to $200 / day

– CPCs and Conversions up 20%

– Fewer keywords

– On the way to fully automating his account

• Third party developers

– Consultants and toolkits are popping up

SOAP, WSDL, and ReST

Web service buzzwords

• SOAP: (formerly) Simple Object Access Protocol

– XML protocol for creating web services

• WSDL: Web Services Definition Language

– Standard for formally describing SOAP services

– Uses XML Schema as a type system

• WS-I Basic Profile

– Best practices / standards for SOAP and WSDL

• WS-*: web services technologies

– WS-Transfer WS-Enumeration WS-Choreography WS-Security WS-Addressing WS-Trust WS-Transactions WS-Federation WS-SecureConversation WS-Reliability WS-Eventing …

• ReST: Representational State Transfer

– Alternative style of creating web services

Why SOAP and WSDL?

• Goal: make this simple program work:

adwords = makeProxy(‘http://.../KeywordService’,

‘nelson’, ‘ossifrage’)

adwords.setKeywordMaxCpc(53834, ‘flowers’, $0.05)

• No XML, no HTTP, just function calls

• WSDL enables this (in theory)

What is SOAP, really?

• XML over HTTP / HTTPS

• Standard way to add metadata (SOAP headers)

• Standard way to signal errors (SOAP faults)

• “Standard” ways to do fancy WS-* things

– Jury is still out on this one

• Document/literal SOAP

• WS-I Basic Profile

Document / literal SOAP example

<?xml version='1.0' encoding='UTF-8'?>

<soap:Envelope>

xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"

xmlns="http://adwords.google.com/api/adwords/v2/">

<soap:Header>

<username>nelson</username>

<password>ossifrage</password>

</soap:Header>

<soap:Body>

<setKeywordMaxCpc>

<adgroupId>53834</adgroupId>

<keyword>flowers</keyword>

<cpc>50000</cpc>

</setKeywordMaxCpc>

</soap:Body>

</soap:Envelope>

Document / literal SOAP

• Stop thinking of API as function calls

• Think of it as passing XML documents around

– Data model is center of design

– Use XML fully (beware: interop)

– Larger requests, more structure

• Beware: no good solution for versioning

• XML data bindings are the key technology

• Get rid of SOAP toolkits entirely?

– But then the simple program isn’t simple

SOAP and WSDL in reality

• Interoperability is still very hard

• WSDL support varies by toolkit

• SOAP document/literal support varies by toolkit

• Good: .NET, Java (Axis)

• OK: C++ (gSOAP), Perl (SOAP::Lite)

• Not good: Python (SOAPpy, ZSI), PHP (many options)

Interop example: sending nothing is hard

Use case: a foo, which is an integer (xsd:int)

<foo>3</foo>

How do you indicate the absence of foo?

<foo xsi:nil=“true”/>

<foo/>

nothing

<foo>-1</foo>

Interop example: sending nothing is hard

<foo xsi:nil=“true”/>

Axis sends by default, .NET fails

<foo/>

not valid (empty string is not an integer)

nothing

Can make Axis send, .NET understands it

<foo>-1</foo>

Weak! But may be easiest.

SOAP interop hazards

• Nested complex objects

• Polymorphic objects

• Optional fields

• Overloaded methods (WS-I forbids this)

• xsi:type considered harmful

• WS-* is all over the map

• Document/literal support is weak in many languages

– Only real choice now

• You can always give up and parse the XML directly

So why not just use ReST?

• Low ReST: use GETs everywhere, they’re easy!

– Friendly hackability

– Can tinker in a browser

– Note: GETs must not have side effects.

• High ReST: use HTTP semantics to build APIs

– Use HTTP verbs GET, POST, PUT, DELETE

– Use URL path meaningfully

– Use XML if you need it, but only as documents

– Metadata in HTTP headers

ReST example

POST http://adwords.google.com/adgroups/53834/flowers/cpc

Content-Type: text/plain

Authorization: Basic 5hq5ADSTZgwt0vWS

50000

ReST limitations

• Less advantage for lots of state changing calls

– End up not using GET much

– PUT, DELETE not implemented uniformly

• No standard structured fault mechanism

• URLs have practical length limits

• No WSDL, no data binding tools

• For complex data, the XML is what really matters

– Will be the same whether ReST or doc/lit SOAP

• For mostly read-only APIs, ReST is good

• Would love to see more ReST tools, conventions

Lessons from experience

Things that went right

• Switch to document/literal

• Stateless design

• Developer reference guide

• Developer tokens

• Thorough interoperability testing

• Private beta period

• Excellent technical support group

Things that went right: bulk methods

• getAdGroup(342343)

• getAdGroups([342343, 342344, 834325])

• Bulk calls up to 25x more efficient

– Less HTTP overhead

– Batch the work in the database

• Problems

– Handling errors in bulk edit methods

– Larger messages

Things that went wrong

• Switch to document/literal

• Lack of a common data model

• Dates and time zones

– What day is 2005-03-09T00:00:00Z?

• No gzip encoding

• Quota confusion and anxiety

• No developer sandbox

Things that went wrong: SSL

• Helping users debug SOAP is hard

• SSL means you can’t easily use sniffer tools

– No SOAPScope, no Ethereal

• Plaintext passwords mean SOAP is secret

– Can’t simply post XML dumps to the public

• SSL is not fast

• Is WS-Security the solution?

– Message level security, not transport

– Looks good, but can we rely on it?

Be sure to get right: SOAP

• Use document/literal

– Don’t use multirefs

• Don’t send xsi:type attributes

• Validate everything: SOAP, WSDL

– Follow WS-I Basic Profile

– SOAPScope is a useful tool

• Test in every language you care about

– Must test every kind of data type

• Consider distributing client libraries

Be sure to get right: developer support

• High quality reference docs

• Sample programs and XML

• Best practices

• Support plan with quick answers to questions

• Debugging instructions

• Developer community