It seems like the browser you are using has JavaScript disabled. As a result, the site will not function properly. We really want you to enable it so you may experience our site as we intended it. If you have no idea what we are talking about or if you need help, visit http://www.enable-javascript.com×
This website uses cookies. By continuing to browse this site you are agreeing to our use of cookies. Find out more on our cookie page.×

Oops, it seems like you're using an old browser that we do not fully support. If you're able to, please upgrade your browser here.×
This website uses cookies. By continuing to browse this site you are agreeing to our use of cookies. Find out more on our cookie page.×

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.

Complete one of the following:

In Windows and
Linux, on the
Window
menu, click Preferences.

In Mac
OS,
on the Momentics
menu, click Preferences.

Expand BlackBerry, and
then click API Level.

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:

In the Project Explorer view,
right-click your project, and then click Properties.

In the Project Explorer view, expand
your project and open the bar-descriptor.xml file.

On the General tab, expand the
API Level section, and then select Explicitly set the platform version.

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.

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.

On the Help menu, click Update API Levels.

In the API Levels
dialog box, select the tab for the type of API level that you want to install
(Gold or Beta).

Click Install for the API level that you want to
install.

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.

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-03-31

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

1. Download the tools

Before you start developing, you'll need to visit the Downloads tab. Here you'll find downloads for the BlackBerry 10 Native SDK, BlackBerry 10 Device Simulator, and some other useful tools.

2. Try the sample apps

Now featuring a filter control, the Sample apps tab allows you to search for samples by name or by feature.

Select either the Core or Cascades radio buttons to display the samples relevant to you.

3. Educate yourself

The Documentation tab contains tons of examples, tutorials, and best practices to guide you along the path towards building an awesome app.

You can access all the documentation that you need in the left-hand navigation.

4. Start developing

The Reference tab is where you'll find essential details about how to use our APIs.

You can use the left-hand navigation to choose how you would like to browse the reference: by module, by topic, or alphabetically. If you have an idea of what you are looking for, start typing it in the Filter box.