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 choose the version of the BlackBerry 10 OS that your app is compatible with.

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

API levels also correspond to a version of the Momentics IDE for BlackBerry. To use a particular API level, you must also use a Momentics IDE version that supports it. The Momentics IDE is backward compatible with older API levels, but it is not forward compatible with newer API levels. When you download a newer API level that your Momentics IDE version does not support, your Momentics IDE updates automatically.

You can select Use Global as your API level to apply the same API level to all of your projects or you can specify an API level for each project that 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 a set of devices. When you select an API level, you see a list of devices that the API level supports. 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, because API levels are backward compatible, you can run an app with a lower API level on a device with a higher API level.

To deploy your app on a device with an OS version that supports a lower API level, do one of the following:

  • Upgrade the OS version on the device (the device runtime).
  • Download a simulator that matches the API level that the app uses.
  • Downgrade the app API level to one that supports the device. You can either select a different installed API level or download another one.

Set the global API level

You can use the global API level to manage the API level for multiple projects in your workspace. By default, the global API level is the latest installed API level. If you set the API level for a project to Use Global, it uses the global API level. When you change the global API level, it updates the API level for all projects in the workspace that use the global setting.

By default, new projects use the global API level. The first time that you start the Momentics IDE, you can complete the Download and Install SDK wizard and install an API level. That API level becomes the global API level.

You can change the global API level and the API level for a specific project at any time.

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

Set the API level for your project

You can select a specific API level to use for any project. The API level determines which version of the BlackBerry 10 OS your app is compatible with.

The API level that you select also sets the minimum platform version for your app. You must use the same platform version when you publish your app on the BlackBerry World storefront. For more information and to submit your app, see BlackBerry World.

To change the API level of an existing project:

  1. In the Project Explorer view, right-click your project, and then click Properties.
  2. Click BlackBerry API Level and select the API level that your project supports from the drop-down list.
  3. Click Apply, and then click OK.

When you set the API level for your project, it updates the platform version number that is used when you package your app. 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 view, expand your project and open the bar-descriptor.xml file.
  2. On the General tab, expand the API Level section, and then select 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.

Control app flow based on API level

In most cases, you select the API level that includes all the functionality required by your app and build one executable that works on devices running that level and later. In certain cases, you might want to produce versions for different API levels. You can use one code base to produce binaries for different API levels by using the macros from bbndk.h to control which code is used for each version.

The BBNDK_VERSION_CURRENT macro contains the API level of the project that you're working on. The BBNDK_VERSION_AT_LEAST(major,minor,patch) macro tests if the (major,minor,patch) API level is at least as high as that of BBNDK_VERSION_CURRENT. You can use these macros in your app's logic to control what to do, based on the API level. For example, suppose you're building an app that has separate versions built for different OS levels. The following code sample shows how to use the BBNDK_VERSION_AT_LEAST(major,minor,patch) macro to control application logic.

// Add logic used by the 10.3.0+ binary here

// Add logic used by the 10.2.1+ binary here

// Add logic used by the 10.0.0+ binary here


In the code sample above, running the app built using a 10.3.0 API level executes the first set of logic, running the app that was built using a 10.2.1 API level runs the second set of logic, and running the app built using an API level below 10.2.1 runs the final set of logic.

Last modified: 2015-07-24

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

comments powered by Disqus