API levels

An API level determines which APIs are available for you to use in your app. The API level corresponds to a version of the BlackBerry 10 OS (for example, 10.0, 10.1, and 10.2). When you create a project for your app and select an API level, you are choosing the version of the BlackBerry 10 OS that your app is compatible with.

The API level is backward compatible. Higher API levels include all the APIs from lower API levels. APIs are deprecated, but are not removed, to ensure that existing apps can continue to use them.

You can select Use Global as your API level to use the global API level that applies to all of your projects or you can specify an API level for each project you create. By default, new projects use the global API level. If you update the global API level, the API level of your project changes automatically.

API levels and supported devices

Each API level supports particular devices. When you select an API level, you see a list of devices that the API level is supported on. The API level of your app must correspond to the API level of the device that you want to run your app on.

Apps that are developed with a lower API level are supported on existing devices, and can reach a broader market. However, apps that are developed with a higher API level can take advantage of a richer set of APIs and features.

If your app uses APIs that were introduced in a higher API level, you can't install the app on a device with a lower API level. However, you can run an app with a lower API level on a device with a higher API level, because API levels are backward compatible.

Change the API level

In the Momentics IDE for BlackBerry, you can change the global API level and the API level for a specific project at any time.

To change the global API level:

  1. In Windows and Linux, on the Window menu, click Preferences. In Mac OS, on the Momentics menu, click Preferences.
  2. Expand BlackBerry and click API Level.
  3. Select the API level to use for all projects that have the Use Global option set.

To change the API level of an existing project:

  1. Select your project in the Project Explorer.
  2. Right-click the project and click Properties.
  3. Click BlackBerry API Level and select the API level that your project supports from the drop-down list.
  4. Click Apply and click OK.

When you set the API level for your project, it updates the platform version number that is used when you package your application. You can set the platform version explicitly in the bar-descriptor.xml file.

To set the platform version in the bar-descriptor.xml file:

  1. In the Project Explorer, expand your project, and then open the bar-descriptor.xml file.
  2. On the General tab, expand the API Level section, and then click Explicitly set the platform version.
  3. In the Platform version field, type the version of the BlackBerry 10 OS that you want to use. You must have an installed API level that targets the specified platform version.
  4. Save your changes.

Download and install an API level

You can download and install a new API level from the Help menu. After you download a new API level, you can use it with any project.

  1. On the Help menu, click Update API Levels.
  2. In the API Levels dialog box, select the tab for the type of API level that you want to install (Gold or Beta).
  3. Click Install for the API level that you want to install.
  4. When the API level finishes installing, click OK.

You can also install a Custom API level by selecting the Custom tab in the API Levels dialog box and clicking Add New Custom SDK. You can specify a path to an SDK platform and uniquely name an SDK when you create a custom API level.

Last modified: 2014-06-24

Got questions about leaving a comment? Get answers from our Disqus FAQ.

comments powered by Disqus