Jira Data Center Front-end API

Jira Data Center allows you to interact with its JavaScript API and resources to facilitate building apps. It also includes guarantees we make to ensure the stability of front-end components and their development.

Accessing the APIs

Jira exposes its front-end API via jira-frontend-api plugin. To use it in AMD (either with require or define), you must add the dependencies to your <web-resource> entries that rely on a given API module. As an example for jQuery, <dependency>jira-frontend-api:jquery</dependency>.

If you are using a supported bundler, such as webpack with webresource-webpack-plugin, you can add API modules to the providedDependencies. This will automatically add the necessary XML entries when you import a given module.

require()

Jira Data Center front-end API consists of selected modules exposed via AMD and can be accessed with the global require function. It accepts an array of module names and gives a reference to the dependencies in a callback function.

1
2
require(['jira/api/jquery', 'jira/api/version', 'mycompany/app-init'], function($, jiraVersion, initApp) {
  // requested modules can be accessed now
});

To load a module, you must explicitly include it as a <dependency> in a <web-resource> entry. See the Web Resource Plugin Module documentation for details.

define()

To create your own module, you can specify it with define function:

1
2
define('mycompany/things/helper', ['some', 'module', 'dependencies'], function(some, module, dependencies) {
  var helper = { ... };
  return helper;
});

We recommend to prefix your module definition with your company or app name to avoid clashing with other apps.

You must not use jira/, aui/, atlassian/, and any prefix used by an Atlassian product, because they are reserved prefixes.

Transitive dependencies

We don’t support accessing a resource or API without specifying it as a dependency in a web-resource for the app. You must call APIs explicitly in the require function or as a dependency in the define function.

Notice that Jira private implementation, function signatures, and dependencies might change between bugfix releases, so any transitive dependency may cease to exist.

Incorrect:

1
2
define('mycompany/moduleA', ['jira/api/version'], function(jiraVersion) {
  const value = jQuery("#mycompany-feature input").val(); // illegal usage of jQuery, even if jQuery is used as a dependency for jira/api/version
});

Correct:

1
2
define('mycompany/moduleA', ['jira/api/version', 'jira/api/jquery'], function(jiraVersion, jQuery) {
  const value = jQuery("#mycompany-feature input").val(); // correct - jQuery specified as dependency
});

You should also specify the dependencies in your <web-resource>, typically in atlassian-plugin.xml:

1
2
<web-resource key="..." name="...">
    <dependency>jira-frontend-api:version</dependency>
    <dependency>jira-frontend-api:jquery</dependency>
    
    <resource .../>
</web-resource>

Web Resource contexts

Web Resource Manager contexts are a popular way to add front-end resources (CSS, JS) to a page. The usage of wide and already full contexts might slow down Jira significantly and affect pages that are not actively taking advantage of your app’s capabilities.

We discourage using cross-screen contexts usually with the atl. prefix (atl.general in particular). Instead, you should use specific, page-level contexts for your app. This mitigates the impact of your app on Jira's performance.

Contexts spanning multiple pages may be altered even between Jira bugfix releases, whereas those starting with jira. or atl.jira (specialized, page-level contexts) will be changed only in feature releases. We’ll announce such changes and new contexts with the affected EAP releases. The addition or the removal of contexts may be introduced in Jira feature releases.

Check WRM Resource loading phases how to utilize various Resource phases and load your JS in a non-blocking way.

Web Resource deprecation

Pay attention to the restricted and deprecated tags in web resources you load, especially those outside the official API. These keywords indicate the support status of the dependencies.

Note that in case of AUI dependencies, the deprecation status corresponds to the AUI version, not the Jira version.

However, most of the resources relate to a Jira version. For example:

1
2
<deprecated since="8.4.0" remove="9.0.0" alternative="jira.webresources:marionette-4.1">
    Use marionette 4.1 for more performant views and cleaner API
</deprecated>

For more information, see web resource documentation.

You can expect that this resource is not stable or guaranteed to appear, even in a bugfix release after deprecated version. Such message will appear in development console:

1
2
[DEPRECATED] "com.atlassian.auiplugin:jquery-spin" has been deprecated since 8.0.0 and will be removed in 10.0.0. Use com.atlassian.auiplugin:aui-spinner instead. Using <aui-spinner/> through jQuery is deprecated. Create a spinner element directly. (required by "com.mycompany.plugin:feature")

DOM tree

Many apps rely on our DOM structure to fetch data. Instead, public REST API or WRM data providers should be used whenever possible. Using the DOM tree to store or to get information is discouraged.

To support app vendors, Jira developers commit to announce major DOM tree structure or stylesheet changes with EAP releases.

AUI components

Atlassian supports the AUI user interface library. You might want to use it to provide a seamless UI experience with your app.

To use AUI components, an app must specify the AUI component web-resource key as a dependency for a given <web-resource> where the AUI component is used.

AUI components provide you with both a web resource key and an AMD module key. For example, to use a banner, you need to add it as a dependency:

<dependency>com.atlassian.auiplugin:aui-banner</dependency>

Then, require its AMD module in your code:

1
2
define('mycompany/feature', ['aui/banner'], function (banner) {
  banner({
    body: 'Your <strong>license has expired!</strong> There are two days left to <a href="#">renew your license</a>.'
  });
});

You might notice AMD modules with names related to AUI or wrappers over these components, but we don’t recommend to use these in your apps (internal modules such as jira/ajs/...). Internal Jira APIs might be unstable between bugfix releases.

Jira API modules

The following table lists available modules:

Code sharing

To decrease page load times, avoid using your own versions of popular libraries like jQuery. Apart from performance reasons, some libraries keep the internal state (e.g. jQuery) or are coupled with its particular instance (e.g. the usage of instanceof in backbone). As a result, for compatibility, interoperability, and better performance, we recommend re-using libraries provided by the API.

Regular modules for the common libraries are versioned up to the minor version (x.y), for example under the jira-frontend-api:react-18.3 web-resource Jira provides React 18.3.1, at the time of writing. The patch version (aka bugfix) can be changed at any time, for example the same web-resource can provide React 18.3.2 in the future.

The alias modules are versioned up to the major version (x), for example under the jira-frontend-api:react-18 web-resource Jira provides React 18.3.1, at the time of writing. The minor version can be changed at any time, for example the same web-resource can provide React 18.4.0 in the future.

The following table lists available modules:

The following table lists deprecated modules:

Recommendations and good practices

While it’s possible to access all DOM content, stylesheet rules, global JavaScript methods, and all WRM resources available through the plugin system, such behavior is discouraged.

Internal modules

We don’t recommend to use modules starting with jira other than the ones on the API list (jira/api).

Method names preceded by an underscore (_) should be considered private and unstable.

Performant and non-intrusive apps

Check WRM Resource loading phases how to utilize various Resource phases and load your JS in a non-blocking way.

• Load only necessary product and apps bootstrapping and init. code in the require phase.
• Execute other parts of the “critical path" in the defer phase.
• Add the remaining code to the interaction phase or lazy-load it.
• Load your app resources only on pages where it operates.
• Split the app code and load selectively.
• Re-use code and libraries when it makes sense.
• The error in the app should not impact the rest of the page.
• Build the app ready to scale with customers and their data.
• Test the app across all supported platforms.

Entering into force

This contract will enter into force with first public release of Jira 9.0.0.

We would like to hear your feedback. Ask your questions using the jira-data-center and jiradc-frontend-api tags on the Developers Forums.

Changelog

Changes to this contract and API modules are also shared as changelog entries:

• https://developer.atlassian.com/server/jira/platform/changelog/#CHANGE-1806 Jira 10.0 related changes