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.

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 a Momentics IDE for BlackBerry version. 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.

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.

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 Momentics 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. 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 later API level. These applications are supported on more devices and can reach a broader market. However, applications that are developed with a later 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 service provider. API levels are not backward compatible with earlier BlackBerry 10 OS versions. You cannot run an application with a later API level on a device 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:
  • Upgrade the OS version on the device (the device runtime).
  • Download a simulator that matches the API level that the application uses.
  • Downgrade the application's API level 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 Momentics 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 Momentics IDE. It also determines which version of the BlackBerry 10 OS 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 App World. For more information and to submit your application, see BlackBerry App 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

The platform version is interpreted as the minimum API level that your application requires. You must have an installed API level that covers the specified platform version.

The platform version is a guideline that is used for verification. When you build the project, the Momentics IDE uses the API level that you set at the project level, using either the global setting or a specific API level.

  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 can have up to four numeric segments, such as 10 or 10.1.0.
  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: 2014-06-24



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

comments powered by Disqus