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