RKG Logo 434-978-4300

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
      • looks like a bug workaround, as field supposed to be nullable!
  • Inherited classes (eg: Ad to TextAd and MobileAd)
  • 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?

 

corn

 

If you like this post, consider subscribing to our RSS feed. You can also have new posts sent to you via email.


Related Posts

Your Comment

Tags

RKG Tags: , , ,

Technorati Tags: , , ,

Trackback

http://www.rimmkaufman.com/rkgblog/2008/07/16/msn-api-v51-upgrade/trackback/

Blogs Citing This Post

  1. Pingback: SearchCap: The Day In Search, July 17, 2008 | PAGE PROPELLER NEWS on July 17, 2008
  2. Pingback: On Writing Effective Blog Post Titles on August 13, 2008

Email Updates

Categories

Recent Comments

  • Nancy Kast: I am writing about your billing and online services. I have been receiving calls saying my bill is not paid. My husband pays all our...
  • Marc Adelman: George, Thanks for sharing this data. From an online buzz perspective, Bing is making a big splash. Everyone is talking about it....
  • George Michie: Hi Dennis, I’m not a lawyer, so take anything I say on this with a grain of salt (and please don’t sue us if we’re...
  • survey online: unfortunatelly i have to say that Google tools are the easiest survey web
  • Dennis Yu: Alan, We’ve had several C&D’s sent to us for seemingly innocuous issues. One of our casual dining clients bid on a...
  • George Michie: Hi Vivek, Haven’t had time to put together a full update, but I did take a look at the numbers. No material gains in market...
  • Karridy: You should checkout ClickPath’s call to KW tracking.
  • Vivek: George, really enjoying reading about the analysis you guys do. Was wondering if you have an update on this given a couple more weeks have...
  • Vicki Swaim: Dear Mr.Ullman, I hope you can help me with my problem. I ordered a TV stand the end of April that was advertised as a close out item....
  • Luke: It’s a shame we live in such a litigious society. Why should we have to set up an association? Surely we can prevent senseless...
  • George Michie: Josh, we have had shots fired over our bow and our client’s in the past. Usually responsible companies are reasonable about...
  • Ryan: Ok, George, I’m sufficiently scared… Thanks… :-) Incidentally, are there any trademark resources (other than Google...
  • Josh: We have run into trademark issues for several clients, although it has so far been a matter of trying to make “fair use” of a...
  • Mike: THANK YOU! I love you man!! :)
  • Matthew: Francis, We’ve likewise seen the “A-List” phenomenon in the past. Perhaps with Bing.com, there won’t be anymore of...

Blog Stats

  • Posts: 871
  • Words: 392,916
  • Comments: 2,079

Administration