Nelson Minar on the Google AdWords API (click to enlarge)

AdWords is the little ads on the side of Google's page and the also show up on third party sites. The traditional way to do campaign management is done by Web application. But, when an advertiser has 1000's of keywords, its hard to manage them through a Web application. There's a hierarchical data model: campaigns contain adwords which contain keywords.

The goal of the API is to allow developers to integrate with the AdWords platform. There are a number of applications: typical bid management, ROI optimization, keyword optimization, integrating advertising with backend systems, and new UI ideas. Nelson wants to create a third party developer community who can add value on top of the platform.

Primary features:

• Campaign management functions
• Reporting functions
• Traffic estimator functions

The core technologies are:

• SOAP+WSDL+SSL
• Quota system
• Multiple authentication mechanisms (there's a hierachical relationship between accounts where some accounts have rights to manage other accounts)

There are retailers using the API to manage seasonal CPCs, third party developers making tools, and small users changing their spend and increasing their click-thrus.

Nelson's goal was to make simple function calls work so that API doesn't require developers to know XML.

Their experience was that interoperability is still hard. WSDL support varies by toolkit. SOAP document/literal support also varies by toolkit. Here's his breakdown:

• Good: .NET, Java (Axis)
• OK: C++ (gSOAP), PERL (SOAP::Lite)
• Not good: Python (SOAPpy, ZSI), PHP (many options)

Here's a real world example of interop problems: Sending nothing is hard. You could send:

<foo xsi:nil="true"/>
<foo/>
nothing
<foo>-1</foo>

Axis likes the first, but .NET fials, the second is not valid. The third is OK, the last =may be the easiest.

Here are some hazards:

• Nested complex objects can work.
• Polymorphic objects are a challenge.
• Optional fields can cause grief (see last example).
• Overloaded methods are forbidden.
• xsi:type considered harmful. This can make apps fragile. Send untyped documents.
• WS-* is all over the map.
• Document/literal support is weak in many languages.

He characterizes REST as "low REST" and "high REST." Low REST is GETS everyewhere. High REST uses HTTP semantics to build APIs. In High REST:

• Use HTTP verbs: GET, POST, PUT, DELETE
• Use URL path meaningfully
• Use XML is you need it, but only as document
• Metadata in HTTP headers

He notes some limitations:

• Less advantage for lots of state changing operations. You don't use GET much and PUt and DELETE are not implemented uniformly.
• No standard fault mechanism
• URLs have practical length limitations
• No WSDL, no data binding tools
• For complex data, the XML is what really matters (i.e. will be the same in REST or SOAP's Doc/lit model)
• For mostly read-only APIs, REST is good
• Need more REST tools and conventions

What went right:

• Switch to doc/li
• Stateless design
• Developer reference guide
• Developer tokens
• Thorough interop testing
• Beta period
• Bulk methods: every method works with a single item or an array and works consistently in either case. A 25 time speed up for some apps. Error semantics is difficult.

Things that went wrong:

• Switch to doc/lit. Cost a lot of time
• Lack of a common data model
• Dates and timezones
• No gzip encoding
• Quota confusion and anxiety
• No developer sandbox
• Helping users debug SOAP is hard
• SSL means you can't use sniffer tools (don't use transport/channel encryption)
• Plaintext passwords mean SOAP is secret. You can't post XML dumps to the public
• SSL is not fast

WS-Security might be the answer, but can we rely on it?

Some more:

• Don't use multirefs
• Don't send xsi:type attributes
• Validate everything: SOAP, WSDL, and follow the WS-I Basic profile
• Test in every language that you care about.

To create a program for user:

• High quality reference docs
• Sample programs and XML
• Best practices
• Support plan with answers to FAQs