Today on the Android Developers blog, the team announced newly available publicly documented APIs in its latest Android OS, Ice Cream Sandwich (ICS). The Android team discussed a bit about why not all APIs are publicly documented even though the operating system is open source:

In almost every case, there’s only one reason for leaving APIs undocumented: We’re not sure that what we have now is the best solution, and we think we might have to improve it, and we’re not prepared to make those commitments to testing and preservation.

We’re not claiming that they’re “Private” or “Secret” — How could they be, when anyone in the world can discover them? We’re also not claiming they’re forbidden: If you use them, your code will compile and probably run. And in fact we know of quite a few apps out there whose developers have used undocumented APIs, often to good effect. It’s hard to get too upset about this in cases where there’s a useful API that we haven’t gotten around to stabilizing.

This is following the Google API trend of not rolling out public APIs too quickly, as to not upset the developer community who is creating and integrating features quickly for their applications.

The new publicly available APIs include Calendar and Text To Speech, probably the two most sought after features of Android’s operating system for developers.

The team had this to say about Calendar:

Let’s start with the good news: As of ICS, the Android Framework will include a fully-worked-out set of APIs for accessing Calendar data. You can guess the bad news: Quite a few developers have built apps (including many good ones) using the undocumented Calendar APIs, some using fairly low-level access to the calendar database. Unfortunately, these integrations were unsupported, and prone to breakage by platform updates or OEM customization of calendar features.

We want to see lots of good calendar apps and extensions that work reliably across Android devices, and aren’t broken by platform updates. So we decided to create a clean API, including a comprehensive set of Intents, to manage calendar data in ICS. Now anyone can code against these new APIs and know that Android is committed to supporting them, and that partners have to support these APIs as part of CTS.

Once the new APIs arrive, you’re going to have to update your apps before they’ll run correctly on ICS while still working on older releases. There are a variety of techniques for doing that, many of which have been featured on this blog, including reflection and lazy loading. Recently, we introduced Multiple-APK support, which could also be used to help with this sort of transition.

The downside of developers using undocumented APIs is that they run the risk of having to update their apps, but this is one of the known issues with working on open source systems, especially ones that run phones.

There are some heavy updates to the Text To Speech API, and will also cause developers to have to update their apps:

Android has never really had a text-to-speech API at the Framework level, but there was unofficial access at the C++ level. With ICS, we will have a fully-thought-through application-level API running on Dalvik, so you can access it with ordinary Java-language application code.

The old C++ API will no longer be supported, but we’ll have a compatibility layer that you can use to bridge from it to the new API. We think it should be easy to update for ICS with very little work.

Google is making it as easy on developers as possible, mentioning that they will offer a compatibility layer that will act as a bridge between updates. That means that most apps will not break in the interim. That can’t always be said for Apple developers, especially ones who haven’t made their iOS5 udpates as of yet.

The moral of the story is that there are risks in developing features around undocumented APIs on an operating system, but it’s good to know that Google is trying to minimize the impact for hardworking teams, and rewarding them with the information they need to create great applications for the Android platform.