Thursday, April 9, 2009

Instant API

One of the aspects of our current financial crisis I've found interesting is the ability of the US Federal Reserve bank to create additional money out of thin air. How does that work? Do they have some money supply control site where Ben Bernanke enters a number and hits the "Submit" button?

I was reminded of this during this month's CDT call when we discussed fixing some bugs that require making a few non breaking API changes. This is an issue because it's after the API freeze date but I think our underlying problem is how through the best intentions we've created a bunch of API from code that wasn't intended to be.

When I started working on CDT the definition of API was a little loose but mostly described interfaces in a public package that we designated API in the CDT docs. Over time we moved to tighten this up and then finally decided to use the same definition as the platform: roughly any interface or class in a non-internal package was to be considered API. Having the API tooling helped with this considerably and newer code like DSF that was designed with this in mind moved into CDT to set a good example.

But this also means that lots of code in CDT that was probably never intended to be API instantly became API. Sure, it probably could have been designed better in the first place or we could have moved it to internal packages or I could have thought about this more at the CDT Summit instead of watching for the afternoon cookies to be delivered. But now here we are needing to fix bugs and needing to make non breaking changes to do it. On the call I said I thought we should just go ahead and make the changes we need and work on a better plan for this next time.

We've just been through something like this with our Carbide sources. We had put all the stuff we thought of as public API into a special SDK plug-in. But as part of open sourcing Carbide for the Symbian Foundation we found ourselves needing to conform to the Eclipse platform definition of API. So we kept ourselves busy for several weeks refactoring things into internal packages so we wouldn't suddenly make a bunch of stuff API that was intended to be internal and private. Now that we've finished and we're testing the result we're finding that we've broken plug-ins people have written for Carbide that were using "non-API" stuff that we renamed. We're reevaluated what we need to make real published API now but it's a good lesson that people will do what they need to in order to get their plug-ins to work and worry about the consequences later on. After all no one wants to create a tool and say to their customers "It doesn't solve your problem or work the way you would expect, but we only used the published APIs!" I guess it's a convoluted form of API requirements gathering.