Launching the
Google AdWords API
Nelson Minar
March 2005
• 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
• 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
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?
• 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'?>
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)
How do you indicate the absence of foo?
<foo xsi:nil=“true”/>
Interop example: sending nothing is hard
<foo xsi:nil=“true”/>
Axis sends by default, .NET fails
not valid (empty string is not an integer)
Can make Axis send, .NET understands it
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 URL path meaningfully
– Use XML if you need it, but only as documents
– Metadata in HTTP headers
ReST example
Content-Type: text/plain
Authorization: Basic 5hq5ADSTZgwt0vWS
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
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

Launching the Google AdWords API