[Update: Confirmed] Google May Remove Access To Undocumented/Hidden APIs In Android P

We may earn a commission for purchases made using our links.

Update 2/28/18: Google has published a blog post today confirming the changes. More details at the end of the article.

While some Android enthusiasts are speculating what dessert the next version of Android will be named after, there are some interesting developments going on behind-the-scenes. We’ve spotted a few note-worthy upcoming features in Android P, but a more recent discovery in the Android Open Source Project (AOSP) has proven far more interesting. According to these recent commits, applications may be restricted from accessing APIs that are undocumented in the Android SDK (such as APIs marked by the javadoc’s attribute @hide).

Why this matters

The Android Software Development Kit (SDK) provides developers with API libraries and tools that they need to test and build new Android applications. With each new release of Android comes a whole host of new APIs that are available to developers through the Android SDK. What APIs are available to an app depend on what compileSDKVersion the developer sets. That’s why Google’s new Play Store requirements are so significant—it will force applications to update and migrate to using newer APIs.

Google hosts documentation pages for each class and all of its methods that are available in each API level. These are the set of documented APIs that are available in the official Android SDK. You can browse the list of classes easily using an Android app such as the recently released Android SDK Search app by Android Engineer Jake Wharton.

However, not all APIs that are available in each Android release are documented by Google, or available in the official Android SDK. There are often useful APIs that are undocumented, but are nonetheless very useful. It isn’t recommended that developers build their apps using undocumented, or hidden, APIs, but many do so because there’s simply no alternative if they want to offer a certain feature. Developers that use hidden or undocumented APIs can put themselves at a competitive advantage as well, since they can offer features that their competitors—who stick to the APIs offered by the Android SDK—cannot.

While I cannot provide a list of apps that utilize undocumented APIs (developers probably don’t share which ones they use because it would give their competitors a leg up), the list is probably rather large. Thus, I would conclude that banning access to hidden APIs would be significant. Mark Murphy, founder of Commonsware, agrees:

I agree with the assessment that bulk-banning access to @hide-annotated items will be a big deal, if that comes to pass. Hopefully, few apps access these items as part of key functionality. However, I suspect that lots of name-brand apps use them on occasion, directly or through a library.

What is happening in Android P?

These upcoming changes were first noted by XDA Senior Recognized Developer rovo89, the developer of the Xposed Framework. He pointed out two commits to me, one of which has been merged, which introduces a new build tool called ‘hiddenapi.’ This tool modifies the access flags of all class members within a DEX file if their signatures appear on an input greylist or blacklist, and if so, the marked methods will be treated as internal APIs with restricted access. The other commit describes how the API blacklist works; it prevents access to boot class methods and fields marked by the aforementioned ‘hiddenapi’ that developers may access by static linking, reflection, and JNI.

According to rovo89, the end result of these two changes in Android P is the following:

If these commits get merged, it would mean that apps can no longer use/access hidden APIs, that is classes, methods and fields which are annotated with @hide in AOSP and therefore not part of the official SDK. This wouldn’t be a problem for Xposed modules as I could easily revert those commits or allow modules to also access these APIs. But there are many apps which take advantage of hidden APIs, and those would fail in the future.

Indeed, further commits show that this may be what Google is planning. This commit states the following:

While this particular commit wasn’t merged as it was abandoned in favor of 3 smaller commits, the commit message describes the purpose of these changes. Another set of commits show that Google will suggest alternatives to developers who seek to use non-public APIs:

However, there are often no alternatives to certain hidden APIs. We at XDA can speak from experience here as unfortunately this change may spell the end of some innovative apps, or it may require some big-name apps to reduce their functionality. This upcoming change seems similar in spirit to the recent crackdown on Accessibility Services (that was thankfully paused as Google evaluated innovative uses). While most apps that utilize undocumented APIs do so for benign reasons, there may be some apps that have misused them for nefarious purposes.

Because of this, Google may be locking down access to all hidden APIs in Android P in order to safeguard users from the few that abuse them. It’s hard to say just how much of an impact this may have on users, but if you are a developer considering looking through AOSP to find an innovative use of a hidden API, then you may want to reconsider.

Update: Google Confirms

In a blog post published today, February 28th, Google has confirmed these changes. Citing crash risks for users and subsequently forcing developers to roll out emergency fixes, Google states the company has been gradually shifting towards discouraging developers from accessing non-SDK interfaces. Starting with Android P, the restrictions will expand to cover the Java language interfaces of the SDK.

The company states that “some non-SDK methods and fields will be restricted,” though they did not elaborate on which ones would be restricted. Initially the restriction will focus on interfaces that are rarely used, and for a while the company will allow developers to continue to use non-SDK methods and fields where transitioning to an SDK method is technically challenging. However, eventually the restrictions will broaden, so developers of apps using non-SDK methods should transition as soon as possible in preparation for Android P. As for methods without an SDK alternative, Google is requesting developers to post on their bug tracker with more information.

The next developer preview, ostensibly arriving soon, will allow developers to test existing apps against the blacklist or greylist before the final release.