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 3rd 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