I noticed our engineering team was taking an unusually long time to upgrade our MSN systems from MSN API version 4 to version 5.1, so I asked about it.

“Everything changed,” our project lead replied, “and the documentation is pretty poor.”

In general, one of the characteristics of a good API is stability. Once published, partners in the outside world build code which depend intimately on the API spec. Well-designed APIs evolve slowly, adding and removing features gracefully so partners can adjust their apps to the improvements.

MSN jerked the rudder hard in a new direction going to v 5.1. Below is a list of pitfalls our engineers encountered. Hopefully this list will help others struggling with MSN’s docs.

Beyond MSN’s business challenges competing again Google and Yahoo, this list demonstrates some of the technical challenges MSN is facing with their codebase. To their credit, the MSN API team has responded quickly and knowledgeably to our requests. For that we are grateful. We appreciate the technical help we receive from MSN, and we hope their API stabilizes relatively quickly.

If any MSN folks are reading this, if it would be helpful, our project lead on this recent API upgrade would be glad to share his experiences with you folks on how in the future this could go more smoothly for both sides.

For contrast, about the same time period, our engineers upgraded our platform from Google API v11 to v12.

The Google API upgrade took 20 minutes.

To be fair, Google v11 to v12 was an extremely small and gradual API tweak, a handful of type changes and other little details. Comparing the Google 20 minutes to MSN’s many developer-days of effort is comparing apples to oranges. I would say, though, that Google’s API advances more gradually and more thoughtfully, making Google an easier technical partner than the other engines.

Again, our thanks to the MSN engineers for fielding so many of calls and emails to clarify the docs. The following email snippet indicates some of the places our engineers hit snags.

There there were more of these, but here is a brief list. In overall they changed the external interface, including names, enumerations and methods. This was more like a full rewrite than an upgrade. My biggest negative on the list is the documentation, as this was the cause of much of our frustrations.

And to give credit - MSN responded quickly and knowledgeably to our requests.

• .Net2/asmx (Administration, CustomerManagement, NotificationManagement interfaces) .Net3 (or 3.5?)/wcf (CampaignManagement, Reporting interfaces)
  • changed xml structure (authentication, etc)
  • enforced xml sequence
  • appears to be that the upgrade is not full, likely an internal deadline was not met
• Renamed many fields and classes to comply with industry standards
  • API is for machine communication, so the name only matters to developers, who has to redo the code now
• Changed method enumerations
  • most of these are 1-to-1 renaming enums, what is the point?
  • eg. removing underscores from EasternTime_US_Canada
• Xml arrays for NegativeKeywords (yes, no longer notkeywords)
  • fine, although web-interface uses comma separated list
• Date type of fields
  • communicate as 3 xml tags: year, month, day
  • link to docs
    • looks like a bug workaround, as field supposed to be nullable!
• Inherited classes (eg: Ad to TextAd and MobileAd)
  • readonly “Type” field is set by derived class type
  • http://msdn.microsoft.com/en-us/library/bb671952.aspx
  • creating ads as Ad xml tag with xml attribute of TextAd, but eliminate Type field during soap operations, as it is readonly…
• API DOCUMENTATION
  • bad navigation (needs to click through many pages to get to the right page, unless you know what you need, and use the sidebar then)
  • INCORRECT information
    • Campaign BudgetLimitType field for a while listed v4 enumerations! - incorrect hyperlink (simple MSN internal curl could discover these after removing the old docs from their internal website, like what we do with our website :-))
    • Parameter substitution in some Ad fields were listed without substituion (appears to be fixed by now)
  • offline version for windows framework only
  • xml code snippets are limited and started to appear in June (middle of the upgrade process)
• Why to have fields, which are reserved for future use? (like v4 had APIFlags, which never made to production, and now is eliminated)
  • Nice to see the ideas, where MSN might go
  • But has no value for an API, and makes documentation readability worse as it litters the information with useless stuff
• V5 was retired ~2 months before deadline, and 5.1 took its place (5.1 had some new reserved for future use fields, AND expanding int to long fields)
  • not a big deal, but what is the point to publish deadlines?