Undocumented and Deprecated : APIs you don't want on your "friends" list

 

There are two kinds of APIs you don’t want to make friends with in this world – undocumented and deprecated. They are mysterious and seductive. They allow you to do things we said you couldn’t do. They continue to work even after we said they wouldn’t (sometimes).

 

I have to be honest – I’ve used them to. In my days as a competitive ISV, we did whatever it took to make the application work. I make no apologies about it. It’s hard to write bleeding edge software when you are doing it just like everyone else and never pushing the limits. So be creative – go for it, but understand a couple of things. You are better off staying away from these guys. With their friendship, comes great risk and responsibility…

 

Undocumented APIs

Remember all those books that made a “splash” off undocumented APIs for Windows? It would seem that Microsoft is simply withholding all these great APIs right? Not really. When we expose a new feature or API and make it public, it goes through a rigorous process of being approved. Do developers really need this API? Is there any other way to do it? Could this API be used maliciously? Does it align with our next product/platform releases? The requirement bar to get something added is extremely high and there are good reasons.

 

As a developer, you know that once you expose a feature (API) – it’s nearly impossible to take it back. To do so is a very disruptive process and in the case of APIs, breaks code and compatibility to remove them. If we add too many APIs, then the platforms starts to bloat in size. People will always use APIs in ways we never intended which is a special risk in itself. Testing cycles become more complex, etc.

 

APIs are the foundation of any development work and you need a solid foundation – so we plan carefully.

 

When we publish an API publicly, it’s like a contract between Microsoft and developers that says “we expect you to use this”. It went through all the quality bars, security reviews, etc. It’s also a way to ensure compatibility moving forward. When we change the internals of our code, we try to avoid changing public APIs used to build your application. You are abstracted from the platform details and so Windows applications continues to work. We expect you to be using these APIs and therefore, we’re very careful about what we change.

 

What happens when you use an undocumented API? Let me be blunt -- we have no idea you are doing it and you are on your own. There is no contract. You are calling into code that was not tested for public consumption. There are no guarantees of what the side effects could be or what other dependencies may exist. When we start changing code for version.next, we may unintentionally change the API out from under you. After all, nobody is expected to be using it because we never published it in the SDK. When you call Microsoft Support they will not be able to help you if it’s outside their support boundaries. Again – if we don’t know you are using it, then it’s subject to change without notice. If your application is dependent on an undocumented API for any piece of functionality, it is very likely to break at some point and put us both in a bad place. Neither of us want to be there – so don’t use undocumented APIs. =)

 

Deprecated APIs

These little guys can sneak up on you. When we determine that an old API is obsolete, we flag it as deprecated in the SDK. This means it’s going away and will stop working at some point but we typically make every effort to support it for another 1-2 revisions of the platform. The idea is to give developers time to prepare their apps. The problem is that many developers never review SDK updates for obsolete APIs and find out the hard way (when things stop working). Granted … it takes discipline to do this and it’s not always easy to find a quick list. Jim Wilson just published a new whitepaper on MSDN that covers the current list of APIs being deprecated on Windows Mobile 5.0 and 6  . I recommend you check it out.

 

Backwards Compatibility

If you stay away from undocumented and deprecated APIs, your backward compatibility story will be much better. One of the larger desktop apps I built back in the day was on top of Windows 3.0 APIs (even before Windows for Workgroups). It was in the neighborhood of a million lines of C++ code. We didn’t have a lot of dependencies on 3^rd party components that could break so the vast majority of the app was just Windows API and the C++ runtime. We didn’t assume (hard code) anything about the network, screen size, etc. It was a monster of an app by many standards today. Amazingly, it still runs today on Vista and aside from the Common Color dialog, works just fine. I’m telling you this to support a point… if you stick to standard, supported APIs you can avoid a lot of the common problems that break apps between platform releases.

 

I think our Windows Mobile teams do an amazing job overall at compatibility. Not only do they have to accept the monumental challenges of maintaining backward compatibility – they have to do it under a stringent memory requirement. By and large many old PPC apps built on core APIs and using supported libraries will run on WM6 today (they may not look beautiful on that amazing new screen but they run).

 

All that said…sometimes there are hard decisions to be made that are going to break some apps. We did with areas in Windows Mobile 2003SE and WM5. Opening the doors for better displays in 2003SE meant old application may would need some re-work with their UI. Moving to persistent storage in WM5 meant losing some I/O performance, upgrading all our database code, and making some major memory changes between program/storage that some apps depended on. But look at the benefits now. We have amazing displays and you aren’t losing data because your battery runs out. Tough decisions? Yes… but sometimes you have to move forward to get better.

 

-Reed

Comments

• Anonymous
  August 23, 2007
  The comment has been removed

• Anonymous
  August 24, 2007
  I’m glad you raised those points. POOM is a perfect example for this discussion.  You are right – it’s functional but not the most efficient way to do things and many ISVs went straight to the database to get around it.  We told people not to do it because direct DB access was not supported , but I have to agree – there was no other way to get the performance you needed for some 3rd party PIM applications, so some ISVs did it anyway.  Because the structures we’re never publically exposed, we changed them and those changes broke code for any applications that used unsupported, direct database access.  This is the “risk” I’m talking about with unsupported and deprecated APIs.  Sometimes there are good reasons to go this route, but you assume the risks.   Why not just support direct database access or expose all APIs? As good as it sounds to say something like “don’t use any APIs you don’t expose to ISVs”, that’s a whole lot easier said than done.  Would you let anyone call into your code anywhere they wanted to?  Are all your APIs customer ready?  Do they have any dependencies to system states or other private structures that may have not been properly initialized?  Could they be used maliciously?  Could you guarantee that your app would work if someone was randomly altering the database underneath it?  There is simply no way expose EVERYTHING and ensure any level of platform stability or security.  APIs are an abstraction layer in every sense. Even though the PIM database structures under POOM were subject to “change without notice”, we told developers this was coming for a year+ before WM5 shipped.  We talked about it in webcasts, MEDC, MSDN papers, blogs, etc.  We did our level best to let developers know even though it was unsupported so they would have time to prepare.  We don't want you in this position. Some of the TIMEZONE information is published publically, but if there is anything you guys really need that we don’t publish—LET US KNOW.  Come to MEDC and provide feedback.  If you can’t attend, then be vocal on the community forums.  Ask for things in the MSDN and Windows Mobile blogs.  I’ll be happy to file the feature request.  I can’t promise it will make it in the product right away, but I promise to get your “ask” in there.  Like any software release, features and APIs are prioritized and added based on demand.  If enough people demand a feature – it will happen. http://support.microsoft.com/kb/923953 I pretty much agree with you on #4.  My point was that by sticking to standard APIs things are more likely to work between releases and that puts you in control over your update and release cycle.  That way, you can release an update when it makes business sense for you and not in “reactive” mode when a customer calls to report the app broke on a new device they just bought.   Thanks for your feedback – good points!

• Anonymous
  September 19, 2007
  Lors de vos développements Windows Mobile, vous avez peut-être utilisé ou cherché à utiliser des API

• Anonymous
  July 22, 2008
    July is a special time around Microsoft.  It’s the start of a new fiscal year…