1## 3.1\. Managed API Compatibility
2
3The managed Dalvik bytecode execution environment is the primary vehicle for
4Android applications. The Android application programming interface (API) is the
5set of Android platform interfaces exposed to applications running in the
6managed runtime environment.
7
8Device implementations:
9
10*    [C-0-1] MUST provide complete implementations, including all documented
11     behaviors, of any documented API exposed by the [Android SDK](
12     http://developer.android.com/reference/packages.html)
13     or any API decorated with the “@SystemApi” marker in the upstream Android
14     source code.
15
16*    [C-0-2] MUST support/preserve all classes, methods, and associated elements
17     marked by the TestApi annotation (@TestApi).
18
19*    [C-0-3] MUST NOT omit any managed APIs, alter API interfaces or signatures,
20     deviate from the documented behavior, or include no-ops, except where
21     specifically allowed by this Compatibility Definition.
22
23*    [C-0-4] MUST still keep the APIs present and behave
24     in a reasonable way, even when some hardware features for which Android
25     includes APIs are omitted. See [section 7](#7_hardware_compatibility)
26     for specific requirements for this scenario.
27
28*    [C-0-5] MUST NOT allow third-party apps to use non-SDK interfaces, which
29     are defined as methods and fields in the Java language packages that are
30     in the boot classpath in AOSP, and that do not form part of the public
31     SDK. This includes APIs decorated with the `@hide` annotation but not with
32     a `@SystemAPI`, as described in the [SDK documents](https://developer.android.com/distribute/best-practices/develop/restrictions-non-sdk-interfaces)
33     and private and package-private class members.
34
35*    [C-0-6] MUST ship with each and every non-SDK interface on the same restricted
36     lists as provided via the `greylist`, `greylist-max-o`, `greylist-max-p`,
37     and blacklist flags in `prebuilts/runtime/appcompat/hiddenapi-flags.csv`
38     path for the appropriate API level branch in the AOSP.
39
40*    [C-0-7] MUST support the [signed config](https://source.android.com/devices/tech/dalvik/signed-config)
41     dynamic update mechanism to remove non-SDK interfaces from a restricted list
42     by embedding signed configuration in any APK, using the existing public keys
43     present in AOSP.
44
45     However they:
46
47     *   MAY, if a hidden API is absent or implemented differently on the device
48         implementation, move the hidden API into the blacklist or omit it from
49         all restricted lists (i.e. light-grey, dark-grey, black).
50     *   MAY, if a hidden API does not already exist in the AOSP, add the hidden
51         API to any of the restricted lists (i.e. light-grey, dark-grey, black).
52
53
54### 3.1.1\. Android Extensions
55
56Android supports extending the managed API surface of a particular API level by
57updating the extension version for that API level. The
58`android.os.ext.SdkExtensions.getExtensionVersion(int apiLevel)` API returns the
59extension version of the provided `apiLevel`, if there are extensions for that
60API level.
61
62Android device implementations:
63
64*   [C-0-1] MUST preload the AOSP implementation of both the shared library
65    `ExtShared` and services `ExtServices` with versions greater than or equal to
66    the minimum versions allowed per each API level. For example, Android 7.0
67    device implementations, running API level 24 MUST include at least
68    version 1.
69
70*   [C-0-2] MUST only return valid extension version number that have been
71    defined by the AOSP.
72
73*   [C-0-3] MUST support all the APIs defined by the extension versions
74    returned by `android.os.ext.SdkExtensions.getExtensionVersion(int apiLevel)`
75    in the same manner as other managed APIs are supported, following the
76    requirements in [section 3.1](#3_1_managed-api-compatibility).
77
78### 3.1.2\. Android Library
79
80Due to [Apache HTTP client deprecation](https://developer.android.com/preview/behavior-changes#apache-p),
81device implementations:
82
83*   [C-0-1] MUST NOT place the `org.apache.http.legacy` library in the
84bootclasspath.
85*   [C-0-2] MUST add the `org.apache.http.legacy` library to the application
86classpath only when the app satisfies one of the following conditions:
87    *    Targets API level 28 or lower.
88    *    Declares in its manifest that it needs the library by setting the
89    `android:name` attribute of `<uses-library>` to `org.apache.http.legacy`.
90
91The AOSP implementation meets these requirements.
92