This page contains information and recommendations for Integration Owners related to Jira Cloud. 

Recommendation

We recommend the python-jira library for Python-based solutions. The atlassian-python-api library is not recommended; it has a few authentication bugs that are difficult to diagnose, and some API support is just missing. While it looks official with Atlassian’s name branding, our Atlassian contacts have told us it is not! Neither library handles scoped tokens well, or understands how to refresh OAuth2 tokens.

Changes to ReST APIs to be aware of:

  1. User information retrieval is very different: there are user IDs (Cloud) instead of user names (DC). If an integration looks up user info, or updates user profiles, this may impact it.
  2. Email addresses can be hidden at the user profile level, or globally across the site. That setting affects APIs related to user data such as Get User, so any integrations using email addresses may have impacted functionality.
  3. All custom field IDs will change. 
    • The names should be the same, but there may be edge cases where a custom field name in the DC instance conflicts with a system field added to Cloud. 
    • If an integration works with both stage and production instances of Jira today, the owner(s) may already be familiar with this limitation. 
  4. Service accounts will have to log in to regenerate API tokens.
    • In Cloud there are new "scoped" tokens, but not all APIs have a scope defined yet.
    • We recommend against using scopes at this time, as the vendor has recommended their use for experimental integrations rather than production.
  5. Older JQL search APIs have been replaced.
  6. There are differences in ScriptRunner functions (e.g. “issueFunction in [...]”) in Cloud. You can view some of their documentation of the differences here. 

Information on v2 and v3 APIs

Jira Data Center has v2 APIs, and they're all present and except for the changes listed above, they should be the same and compatible in Cloud. Integration owners may be interested to learn there are v3 APIs available in Cloud, which may be helpful with future maintenance and features. The main features are consistent use of the Atlassian Document Format (ADF) and streamlined user accounting.

  • Differences between v2 and v3 (we use v2 in DC)
    • The level of effort  for most of the basic stuff is expected to be low-to-modest
    • There are some signature changes between v2 in DC and v2 in Cloud
    • There is no guarantee that simply swapping the base URL will result in the same API behavior in Cloud
    • V3 has bulk edit API operations if you know the IDs
    • Most of the rework will be endpoints that require signature changes
    • Search APIs have changed - only issue IDs are returned, and you have to define what fields return (this requires changes to pagination logic)
    • Atlassian Doc Format (ADF) is a feature of v3 APIs, and will be the way going forward.
  • Recommendation: 
    • if a v2 API would require a signature change, move to the v3 version.
    • If a v2 API does not require a signature change, stay on the v2 version.
    • Developing new scripts should default to using v3.
    • Subscribe to changelog RSS feed.
  • No labels