I think we can all agree that building a software product is difficult. What’s even more difficult is maintaining it. It’s particularly difficult and frustrating when the APIs you’ve come to depend on change from under you. Changing APIs between minor releases negatively affects the developers who rely on it for their products, the customers who bought that developer’s product, and the users of that product. This is a problem with many software ecosystems today and that used to be the case for plugin developers building off of the JIRA APIs.

For JIRA 5, we spent a significant amount of engineering effort building the foundation for stable Java APIs. The result of this effort is an API policy that boils down to forwards compatibility throughout all minor releases in a major release family. For example, a plugin that is built against JIRA 5 will continue to work with JIRA 5.1, 5.2, and so on, without being recompiled. Minor releases may add a new API, but it will be binary compatible with the API from previous releases in the same major release family.

The JIRA 5 Java APIs are now split up into two Maven artifacts:

  • jira-api (aka, the stable API) – classes or interfaces in this module are considered a part of JIRA’s Java API, and we will maintain binary compatibility for these classes and interfaces.
  • jira-core – contains internal JIRA classes (sometimes call ‘implementation classes’). Plugin developers may have a dependency on jira-core and use any of these implementation classes, but the underlying code may change even in bug-fix releases.

To make use of the stable API, make sure your plugin references the following Maven dependency:

<dependency>
    <groupId>com.atlassian.jira</groupId>
    <artifactId>jira-api</artifactId>
    <version>${atlassian.product.version}</version>
    <scope>provided</scope>
</dependency>

Why should I care?

The basic gist of all of this is that if a plugin uses the APIs in jira-api, that plugin will not break due to an API change across all 5.x releases (because we guarantee that there will be no API changes to jira-api in all 5.x releases). However, if a plugin uses an internal API (found in jira-core), that plugin might break across a 5.x release.

For more information about this policy, please visit the official JIRA API policy page. The stable API’s reference documentation is available on developer.atlassian.com.

We’ve also built the Atlassian Plugin Checkup tool that will allow plugin developers to analyze their plugin’s API usage. If you’re a JIRA plugin developer, please use the Plugin Checkup to verify your stable API usage.