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 includes the support of extending the managed APIs while keeping the
57same API level version.
58
59*   [C-0-1] Android device implementations MUST preload the AOSP implementation
60of both the shared library `ExtShared` and services `ExtServices` with versions
61higher than or equal to the minimum versions allowed per each API level.
62For example, Android 7.0 device implementations, running API level 24 MUST
63include at least version 1.
64
65### 3.1.2\. Android Library
66
67Due to [Apache HTTP client deprecation](https://developer.android.com/preview/behavior-changes#apache-p),
68device implementations:
69
70*   [C-0-1] MUST NOT place the `org.apache.http.legacy` library in the
71bootclasspath.
72*   [C-0-2] MUST add the `org.apache.http.legacy` library to the application
73classpath only when the app satisfies one of the following conditions:
74    *    Targets API level 28 or lower.
75    *    Declares in its manifest that it needs the library by setting the
76    `android:name` attribute of `<uses-library>` to `org.apache.http.legacy`.
77
78The AOSP implementation meets these requirements.
79