API levels

An API level is a set of APIs and libraries that an application can build against. The API level corresponds to a version of BlackBerry 10 OS, such as 10.0, 10.1, and 10.2. You can download new APIs and develop against a new API level.

API levels are backward compatible. Higher API levels include all the APIs from previous APIs levels. To ensure that existing applications continue to work, APIs are deprecated but are not removed.

API levels also correspond to an IDE version. To use a particular API level, you must also use an IDE version that supports it. The 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 IDE version does not support, your IDE updates automatically.

The API level and device runtime replace the BlackBerry target, which was used in earlier versions. The API level corresponds to a device runtime, which matches the operating system version on your device or simulator and allows you to debug. For information about the device runtime, see Manage devices.

You can use either a global API level that applies to all projects in a workspace, or you can set the API level for an individual project.

API levels and device OS versions

Each API level supports particular devices. When you select an API level in the IDE, you see a list of devices that it supports. The API level of your application corresponds to the BlackBerry 10 OS version on the device.

API levels are forward compatible with later BlackBerry 10 OS versions, which means that you can debug your application on multiple devices without having to change the APIs that your application builds against. You can run applications that are developed with a lower API level on devices that support a higher API level. Consequently, these applications are supported on more devices and can reach a broader market. However, applications that are developed with a higher API level can take advantage of a richer set of APIs and features.

The API level for your application must match the BlackBerry 10 OS version on the device that is provided by your wireless service provider. API levels are not backward compatible with earlier BlackBerry 10 OS versions. You cannot run an application with a higher API level on a device that with an OS version that supports a lower API level. To deploy your application on a device with an OS version that supports a lower API level, do one of the following:
  • Update the OS version on the device.
  • Download a simulator that matches the API level that the application uses.
  • Change the API level of the application to one that supports the device. You can either select a different installed API level or download another one.

Global API level

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 IDE, you can complete the Download and Install SDK wizard and install an API level. That API level becomes the global API level. However, you can change the global API level at any time.

Change the global API level
  1. Do one of the following:
    • On Windows or Linux, on the toolbar, click Window > Preferences.
    • On Mac, on the toolbar, click Momentics > Preferences.
  2. On the Preferences dialog box, expand BlackBerry, and then click API Level.
  3. Select the API level that you want to use, and then click OK.

Set the API level for your application

You can select the API level to use for your project. The API level determines which APIs are available when you develop an application in the IDE, and which version of the BlackBerry 10 OS that your application is compatible with.

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

When you create a project, you set the API level on the New Project Wizard. However, you can change the API level for a project at any time.

Change the API level for a project

  1. In the Project Explorer, right-click your project, and then select Properties.
  2. On the Properties dialog box, click BlackBerry API Level.
  3. Select the API level that you want to use, 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 application. You can explicitly set the platform version in the BAR application descriptor file (bar-descriptor.xml).

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. It must have four numeric segments, such as 10.1.0.0. 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. On the API Levels dialog box, click Install for the API level that you want.
  3. When the API level finishes installing, click OK.

Last modified: 2013-12-21

comments powered by Disqus