Undocumented APIs

Oh, shut up. Slashdot posted this story about Apple being “evil” because they use undocumented APIs on Safari. That’s not evil, that’s NORMAL. In the Agile software development this is important, otherwise you will be having a past generation code for your browser to ship with your next generation OS.

Be, Inc. was doing that all the time too. Many parts of the OS were built using undocumented APIs that were not too stable to become public at the time, or that were simply too low level. The Be scrollbar and the Be Terminal were such examples.

I am sure MS does the same on Windows.


Tom Dison wrote on February 29th, 2008 at 6:45 AM PST:

I had the same feeling. There are lots of undocumented Win32 API functions. I mean, really, who could or would want to document them all? As you said, many are too low level and not really meant for public consumption.

tante wrote on February 29th, 2008 at 6:56 AM PST:

The main issue is that without knowledge of those APIs you are punished with speed problems, effectively giving your company an advantage against any possible competition.

I don’t disagree that Apple and Microsoft both do it, that is actually the problem: If you are the maker of a proprietary operating system and do not open up your APIs completely you are effectively trying to make proper competition impossible. It’s a way to lock people into your software and create monopolies, so I think the people that speak against it are right to do so.

cris wrote on February 29th, 2008 at 8:08 AM PST:

last time I checked, webkit is “open source” while IE is not.

“common corporal practice” doesn’t make it right with OSS.

Dave Rosky wrote on February 29th, 2008 at 8:12 AM PST:

Sorry, Eugenia, I agree with tante on this one (at least partially). I think it really depends on the situation and who you are. If you are the vendor of a very popular (dare I say “necessary”) product, like an operating system (Windows for example), and if you have hidden API’s, then it *could* be a problem. If those API’s are truly just not-yet-stable bits and pieces, then fine, but if those API’s are something that can give your other software a hidden advantage in the market, then it is problematic.

Dave Rosky wrote on February 29th, 2008 at 8:14 AM PST:

Even open source software has undocumented APIs, especially of the not-yet-ready-for-general-use type, although they are ultimately documented by the source code, if you want to read it.

This is the admin speaking...
Eugenia wrote on February 29th, 2008 at 12:06 PM PST:

Dave, I disagree. Some APIs are just not meant for public consumption, because you want to give to people cleaned up versions, or not that low level code. It is a practice that happens on any OS manufacturer, and even Gnome does that when they use sometimes libraries that are brand new and distros haven’t upgraded to these libs yet and now they have. It’s a similar thing, just at a different level.

Dave Rosky wrote on February 29th, 2008 at 1:20 PM PST:

Eugenia, I think I basically agree under those conditions. There are going to be API’s that aren’t ready for general use yet and those APIs shouldn’t be documented. In open source code, where you can always read the source code, you might even want to include a warning against using it.

Where it becomes a problem is if, say, Microsoft included a number of fully mature APIs that provide hooks into the OS, for example, to do certain things much more efficiently and then hide those API’s only for their own use in their own application software. They may not actually do that, but if they do, I think it would be wrong.

Having said that, I’m sure that 99.9% of the undocumented API’s out there are probably of the harmless type you are talking about.

Mr. Me wrote on February 29th, 2008 at 4:22 PM PST:

“The main issue is that without knowledge of those APIs you are punished with speed problems, effectively giving your company an advantage against any possible competition.”

This is not such a case. There is a documented way to get the same ‘advantage’.

But ‘advantage’ is in quotes there for a reason. The private API in question allows the application to disable coalesced screen updates, a relatively new feature in MacOS X which prevented applications from drawing faster than the refresh rate of the display. Disabling this is very much a BAD thing for overall performance: drawing too fast serves no useful purpose, so it wastes CPU cycles (meaning it’s a performance loss when viewed as an opportunity cost) and power.

Why, then, would you want to shoot yourself in the foot? As usual, in order to avoid doing the right thing. Many programs written prior to the advent of coalesced updates accidentally slow down now that the window server acts like a blocking I/O device when the program attempts to draw faster than the display refresh rate. The correct way of handling this is either to decouple display updates from other processing in your application or avoid performing drawing API calls when you know they’ll block, but the quick and dirty way to work around it is to disable coalesced updates.

Neither Firefox nor Safari is doing the right thing by disabling coalesced updates; they both need to fix their behavior to be more clean. But there is in fact a published interface allowing Firefox to shoot itself in the foot too — a simple entry in the property list file in an application’s bundle tells the system to disable coalesced updates for that app.

The private programmatic interface is used by WebKit (the HTML framework which is the basis of the Safari browser) to disable coalesced updates for applications which embed WebKit views. This is not really a good thing for Apple to be doing even from its own perspective, but it avoids introducing performance regressions to non-Apple applications which embed WebKit.

So that’s really the limit of the private-ness — if you want to write a library which disables coalesced updates on behalf of the applications which link to that library, you’re out of luck (or you damn the torpedoes and use the private API).

Comments are closed as this blog post is now archived.

Lines, paragraphs break automatically. HTML allowed: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>

The URI to TrackBack this blog entry is this. And here is the RSS 2.0 for comments on this post.