Creating a new web service at google

Nelson Minar

The Google AdWords API

• Adwords: Campaign management done via a web app. Advertisers select keywords applicable to their ad
• Hierarchical data model. advertisers->campaigns->keywords
• API goals – allow developers to integrate with the platform
• 3rd party companies springing up to tweak keywords for maximum efficiency, or make alternative UIs
• Smart companies integrating their back-office systems with their ad campaigns e.g. when stock runs out, pause the ads
• Features: Campaign management, reporting functions, traffic estimator
• Technologies: SOAP/WSDL over SSL. Quota system; multiple authentication mechanisms (proxying / remote management)
• consultancy and toolkit vendors are starting to spring up.


• Uses SOAP 1.1 + the WS-I basic profile
• objective is to make the integration as simple as possible for a WSDL-enabled application. For a good platform an API call should be 2 lines (make a proxy, call the method)
• uses Document/literal soap rather than RPC-oriented: D/L is closer to ReST/Atom – it's just passing documents about
• Doc/lit soap requires good xml—>native object bindings. Poor binding is a frequent cause of interop problems
• Reality: Interop is still hard; WSDL support varies by toolkit; doc/lit support likewise
• Good platforms: .NET, Java (axis). OK: C++ (gSOAP), Perl (SOAP::Lite) Not good: Python (SOAPpy, ZSI), PHP

interop hazards

• nested complex objects
• polymorphic objects
• optional fields
• overloaded methods
• xsi:type: Since clients keep getting them wrong it's easier to just not bother
• ws-* – only sun and MS support it
• doc/lit support is weak in scripting languages
  …
• or you could just parse the XML yourself.

Why not just use ReST?

• Easy to use
• tinkerable
• high ReST – use the HTTP verbs to build the app, use meaningful URL path, use XML only as a document (payload), use HTTP headers for metadata
• Nelson treats POST as update (c.f. Ben yesterday who considered it to be create)
  limitations
• lack of support for PUT/DELETE from browser – poorly tested in caches
• limited standardisation for error codes
• browsers can't cope with URLs more than 1000 chars
• you've got to do your own databindings – no WSDL

bottom line

• For complex data the XML is what matters and it doesn't make much difference if it's doc/lit soap or ReST
• for read-mostly apps, ReST is best
• need better tooling

Lessons learned
– good things:

• doc/lit
• stateless design
• developer reference guide
• developer tokens
• interop testing
• private beta period
• batch-oriented methods – specify an array of IDs and get back multiple XML entities. big speedups. Makes error semantics harder, and messages larger
  – bad things
• doc/lit switch was expensive
• lack of a common/clear data model
• dates / TZs are wierd – SOAP dates are GMT but google works on PST
• no gzip enconding
• quota confusion / anxiety
• no sandbox
• SSL - hard to sniff, XML dumps aren't publishable because they contain plain-text passwords, slow. note to self we should use a 1-way hash or something for our APIs_


• Make sure your SOAP is well validated and clean: test interop. Distributing a client library is worthwhile
• need good developer support – docs, samples, FAQ, debigging instructions, community

Chris May : 16 Mar 2005 00:33 |  Tags: Etech |  Comments (2) |  Report a problem