1page.title=Android API Levels 2@jd:body 3 4<div id="qv-wrapper"> 5<div id="qv"> 6 7 <h2>In this document</h2> 8<ol> 9 <li><a href="#intro">What is API Level?</a></li> 10 <li><a href="#uses">Uses of API Level in Android</a></li> 11 <li><a href="#considerations">Development Considerations</a> 12 <ol> 13 <li><a href="#fc">Application forward compatibility</a></li> 14 <li><a href="#bc">Application backward compatibility</a></li> 15 <li><a href="#platform">Selecting a platform version and API Level</a></li> 16 <li><a href="#apilevel">Declaring a minimum API Level</a></li> 17 <li><a href="#testing">Testing against higher API Levels</a></li> 18 </ol> 19 </li> 20 <li><a href="#provisional">Using a Provisional API Level</a></li> 21 <li><a href="#filtering">Filtering the Documentation</a></li> 22</ol> 23 24 <h2>See also</h2> 25 <ol> 26 <li><a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html"><uses-sdk></a> manifest element</li> 27 </ol> 28 29</div> 30</div> 31 32<p>As you develop your application on Android, it's useful to understand the 33platform's general approach to API change management. It's also important to 34understand the API Level identifier and the role it plays in ensuring your 35application's compatibility with devices on which it may be installed. </p> 36 37<p>The sections below provide information about API Level and how it affects 38your applications. </p> 39 40<p>For information about how to use the "Filter by API Level" control 41available in the API reference documentation, see 42<a href="#filtering">Filtering the documentation</a> at the 43end of this document. </p> 44 45<h2 id="intro">What is API Level?</h2> 46 47<p>API Level is an integer value that uniquely identifies the framework API 48revision offered by a version of the Android platform.</p> 49 50<p>The Android platform provides a framework API that applications can use to 51interact with the underlying Android system. The framework API consists of:</p> 52 53<ul> 54<li>A core set of packages and classes</li> 55<li>A set of XML elements and attributes for declaring a manifest file</li> 56<li>A set of XML elements and attributes for declaring and accessing resources</li> 57<li>A set of Intents</li> 58<li>A set of permissions that applications can request, as well as permission 59enforcements included in the system</li> 60</ul> 61 62<p>Each successive version of the Android platform can include updates to the 63Android application framework API that it delivers. </p> 64 65<p>Updates to the framework API are designed so that the new API remains 66compatible with earlier versions of the API. That is, most changes in the API 67are additive and introduce new or replacement functionality. As parts of the API 68are upgraded, the older replaced parts are deprecated but are not removed, so 69that existing applications can still use them. In a very small number of cases, 70parts of the API may be modified or removed, although typically such changes are 71only needed to ensure API robustness and application or system security. All 72other API parts from earlier revisions are carried forward without 73modification.</p> 74 75<p>The framework API that an Android platform delivers is specified using an 76integer identifier called "API Level". Each Android platform version supports 77exactly one API Level, although support is implicit for all earlier API Levels 78(down to API Level 1). The initial release of the Android platform provided 79API Level 1 and subsequent releases have incremented the API Level.</p> 80 81<p>The following table specifies the API Level supported by each version of the 82Android platform.</p> 83 84<table> 85 <tr><th>Platform Version</th><th>API Level</th></tr> 86 <tr><td>Android 2.3.3</td><td>10</td></tr> 87 <tr><td>Android 2.3</td><td>9</td></tr> 88 <tr><td>Android 2.2</td><td>8</td></tr> 89 <tr><td>Android 2.1</td><td>7</td></tr> 90 <tr><td>Android 2.0.1</td><td>6</td></tr> 91 <tr><td>Android 2.0</td><td>5</td></tr> 92 <tr><td>Android 1.6</td><td>4</td></tr> 93 <tr><td>Android 1.5</td><td>3</td></tr> 94 <tr><td>Android 1.1</td><td>2</td></tr> 95 <tr><td>Android 1.0</td><td>1</td></tr> 96</table> 97 98 99<h2 id="uses">Uses of API Level in Android</h2> 100 101<p>The API Level identifier serves a key role in ensuring the best possible 102experience for users and application developers: 103 104<ul> 105<li>It lets the Android platform describe the maximum framework API revision 106that it supports</li> 107<li>It lets applications describe the framework API revision that they 108require</li> 109<li>It lets the system negotiate the installation of applications on the user's 110device, such that version-incompatible applications are not installed.</li> 111</ul> 112 113<p>Each Android platform version stores its API Level identifier internally, in 114the Android system itself. </p> 115 116<p>Applications can use a manifest element provided by the framework API — 117<code><uses-sdk></code> — to describe the minimum and maximum API 118Levels under which they are able to run, as well as the preferred API Level that 119they are designed to support. The element offers three key attributes:</p> 120 121<ul> 122<li><code>android:minSdkVersion</code> — Specifies the minimum API Level 123on which the application is able to run. The default value is "1".</li> 124<li><code>android:targetSdkVersion</code> — Specifies the API Level 125on which the application is designed to run. In some cases, this allows the 126application to use manifest elements or behaviors defined in the target 127API Level, rather than being restricted to using only those defined 128for the minimum API Level.</li> 129<li><code>android:maxSdkVersion</code> — Specifies the maximum API Level 130on which the application is able to run. <strong>Important:</strong> Please read the <a 131href="{@docRoot}guide/topics/manifest/uses-sdk-element.html"><code><uses-sdk></code></a> 132documentation before using this attribute. </li> 133</ul> 134 135<p>For example, to specify the minimum system API Level that an application 136requires in order to run, the application would include in its manifest a 137<code><uses-sdk></code> element with a <code>android:minSdkVersion</code> 138attribute. The value of <code>android:minSdkVersion</code> would be the integer 139corresponding to the API Level of the earliest version of the Android platform 140under which the application can run. </p> 141 142<p>When the user attempts to install an application, or when revalidating an 143appplication after a system update, the Android system first checks the 144<code><uses-sdk></code> attributes in the application's manifest and 145compares the values against its own internal API Level. The system allows the 146installation to begin only if these conditions are met:</p> 147 148<ul> 149<li>If a <code>android:minSdkVersion</code> attribute is declared, its value 150must be less than or equal to the system's API Level integer. If not declared, 151the system assumes that the application requires API Level 1. </li> 152<li>If a <code>android:maxSdkVersion</code> attribute is declared, its value 153must be equal to or greater than the system's API Level integer. 154If not declared, the system assumes that the application 155has no maximum API Level. Please read the <a 156href="{@docRoot}guide/topics/manifest/uses-sdk-element.html"><code><uses-sdk></code></a> 157documentation for more information about how the system handles this attribute.</li> 158</ul> 159 160<p>When declared in an application's manifest, a <code><uses-sdk></code> 161element might look like this: </p> 162 163<pre><manifest> 164 <uses-sdk android:minSdkVersion="5" /> 165 ... 166</manifest></pre> 167 168<p>The principal reason that an application would declare an API Level in 169<code>android:minSdkVersion</code> is to tell the Android system that it is 170using APIs that were <em>introduced</em> in the API Level specified. If the 171application were to be somehow installed on a platform with a lower API Level, 172then it would crash at run-time when it tried to access APIs that don't exist. 173The system prevents such an outcome by not allowing the application to be 174installed if the lowest API Level it requires is higher than that of the 175platform version on the target device.</p> 176 177<p>For example, the {@link android.appwidget} package was introduced with API 178Level 3. If an application uses that API, it must declare a 179<code>android:minSdkVersion</code> attribute with a value of "3". The 180application will then be installable on platforms such as Android 1.5 (API Level 1813) and Android 1.6 (API Level 4), but not on the Android 1.1 (API Level 2) and 182Android 1.0 platforms (API Level 1).</p> 183 184<p>For more information about how to specify an application's API Level 185requirements, see the <a 186href="{@docRoot}guide/topics/manifest/uses-sdk-element.html"><code><uses-sdk></code></a> 187 section of the manifest file documentation.</p> 188 189 190<h2 id="considerations">Development Considerations</h2> 191 192<p>The sections below provide information related to API level that you should 193consider when developing your application.</p> 194 195<h3 id="fc">Application forward compatibility</h3> 196 197<p>Android applications are generally forward-compatible with new versions of 198the Android platform.</p> 199 200<p>Because almost all changes to the framework API are additive, an Android 201application developed using any given version of the API (as specified by its 202API Level) is forward-compatible with later versions of the Android platform and 203higher API levels. The application should be able to run on all later versions 204of the Android platform, except in isolated cases where the application uses a 205part of the API that is later removed for some reason. </p> 206 207<p>Forward compatibility is important because many Android-powered devices 208receive over-the-air (OTA) system updates. The user may install your 209application and use it successfully, then later receive an OTA update to a new 210version of the Android platform. Once the update is installed, your application 211will run in a new run-time version of the environment, but one that has the API 212and system capabilities that your application depends on. </p> 213 214<p>In some cases, changes <em>below</em> the API, such those in the underlying 215system itself, may affect your application when it is run in the new 216environment. For that reason it's important for you, as the application 217developer, to understand how the application will look and behave in each system 218environment. To help you test your application on various versions of the Android 219platform, the Android SDK includes multiple platforms that you can download. 220Each platform includes a compatible system image that you can run in an AVD, to 221test your application. </p> 222 223<h3 id="bc">Application backward compatibility</h3> 224 225<p>Android applications are not necessarily backward compatible with versions of 226the Android platform older than the version against which they were compiled. 227</p> 228 229<p>Each new version of the Android platform can include new framework APIs, such 230as those that give applications access to new platform capabilities or replace 231existing API parts. The new APIs are accessible to applications when running on 232the new platform and, as mentioned above, also when running on later versions of 233the platform, as specified by API Level. Conversely, because earlier versions of 234the platform do not include the new APIs, applications that use the new APIs are 235unable to run on those platforms.</p> 236 237<p>Although it's unlikely that an Android-powered device would be downgraded to 238a previous version of the platform, it's important to realize that there are 239likely to be many devices in the field that run earlier versions of the 240platform. Even among devices that receive OTA updates, some might lag and 241might not receive an update for a significant amount of time. </p> 242 243<h3 id="platform">Selecting a platform version and API Level</h3> 244 245<p>When you are developing your application, you will need to choose 246the platform version against which you will compile the application. In 247general, you should compile your application against the lowest possible 248version of the platform that your application can support. 249 250<p>You can determine the lowest possible platform version by compiling the 251application against successively lower build targets. After you determine the 252lowest version, you should create an AVD using the corresponding platform 253version (and API Level) and fully test your application. Make sure to declare a 254<code>android:minSdkVersion</code> attribute in the application's manifest and 255set its value to the API Level of the platform version. </p> 256 257<h3 id="apilevel">Declaring a minimum API Level</h3> 258 259<p>If you build an application that uses APIs or system features introduced in 260the latest platform version, you should set the 261<code>android:minSdkVersion</code> attribute to the API Level of the latest 262platform version. This ensures that users will only be able to install your 263application if their devices are running a compatible version of the Android 264platform. In turn, this ensures that your application can function properly on 265their devices. </p> 266 267<p>If your application uses APIs introduced in the latest platform version but 268does <em>not</em> declare a <code>android:minSdkVersion</code> attribute, then 269it will run properly on devices running the latest version of the platform, but 270<em>not</em> on devices running earlier versions of the platform. In the latter 271case, the application will crash at runtime when it tries to use APIs that don't 272exist on the earlier versions.</p> 273 274<h3 id="testing">Testing against higher API Levels</h3> 275 276<p>After compiling your application, you should make sure to test it on the 277platform specified in the application's <code>android:minSdkVersion</code> 278attribute. To do so, create an AVD that uses the platform version required by 279your application. Additionally, to ensure forward-compatibility, you should run 280and test the application on all platforms that use a higher API Level than that 281used by your application. </p> 282 283<p>The Android SDK includes multiple platform versions that you can use, 284including the latest version, and provides an updater tool that you can use to 285download other platform versions as necessary. </p> 286 287<p>To access the updater, use the <code>android</code> command-line tool, 288located in the <sdk>/tools directory. You can launch the Updater by using 289the <code>android</code> command without specifying any options. You can 290also simply double-click the android.bat (Windows) or android (OS X/Linux) file. 291In ADT, you can also access the updater by selecting 292<strong>Window</strong> > <strong>Android SDK and AVD 293Manager</strong>.</p> 294 295<p>To run your application against different platform versions in the emulator, 296create an AVD for each platform version that you want to test. For more 297information about AVDs, see <a 298href="{@docRoot}guide/developing/tools/avd.html">Android Virtual Devices</a>. If 299you are using a physical device for testing, ensure that you know the API Level 300of the Android platform it runs. See the table at the top of this document for 301a list of platform versions and their API Levels. </p> 302 303 304<h2 id="provisional">Using a Provisional API Level</h2> 305 306<p>In some cases, an "Early Look" Android SDK platform may be available. To let 307you begin developing on the platform although the APIs may not be final, the 308platform's API Level integer will not be specified. You must instead use the 309platform's <em>provisional API Level</em> in your application manifest, in order 310to build applications against the platform. A provisional API Level is not an 311integer, but a string matching the codename of the unreleased platform version. 312The provisional API Level will be specified in the release notes for the Early 313Look SDK release notes and is case-sensitive.</p> 314 315<p>The use of a provisional API Level is designed to protect developers and 316device users from inadvertently publishing or installing applications based on 317the Early Look framework API, which may not run properly on actual devices 318running the final system image.</p> 319 320<p>The provisional API Level will only be valid while using the Early Look SDK 321and can only be used to run applications in the emulator. An application using 322the provisional API Level can never be installed on an Android device. At the 323final release of the platform, you must replace any instances of the provisional 324API Level in your application manifest with the final platform's actual API 325Level integer.</p> 326 327 328<h2 id="filtering">Filtering the Reference Documentation by API Level</h2> 329 330<p>Reference documentation pages on the Android Developers site offer a "Filter 331by API Level" control in the top-right area of each page. You can use the 332control to show documentation only for parts of the API that are actually 333accessible to your application, based on the API Level that it specifies in 334the <code>android:minSdkVersion</code> attribute of its manifest file. </p> 335 336<p>To use filtering, select the checkbox to enable filtering, just below the 337page search box. Then set the "Filter by API Level" control to the same API 338Level as specified by your application. Notice that APIs introduced in a later 339API Level are then grayed out and their content is masked, since they would not 340be accessible to your application. </p> 341 342<p>Filtering by API Level in the documentation does not provide a view 343of what is new or introduced in each API Level — it simply provides a way 344to view the entire API associated with a given API Level, while excluding API 345elements introduced in later API Levels.</p> 346 347<p>If you decide that you don't want to filter the API documentation, just 348disable the feature using the checkbox. By default, API Level filtering is 349disabled, so that you can view the full framework API, regardless of API Level. 350</p> 351 352<p>Also note that the reference documentation for individual API elements 353specifies the API Level at which each element was introduced. The API Level 354for packages and classes is specified as "Since <api level>" at the 355top-right corner of the content area on each documentation page. The API Level 356for class members is specified in their detailed description headers, 357at the right margin. </p> 358