LoginSign UpGet Demo
Get accountRequest Demo
DocumentationIntegrationsTools
BlogChangelogPricingLogin
Back

Jira Data Center API Essential Guide

Aug 9, 2024 • 6 minute read

What type of API does Jira Data Center provide?

Jira Data Center has both REST and GraphQL APIs available:

REST API

Jira Data Center provides a comprehensive REST API. Key points about the Jira REST API include:

  • It uses JSON as the communication format
  • It uses standard HTTP methods like GET, PUT, POST and DELETE
  • The API version is specified in the URL path (e.g. /rest/api/2/)
  • Authentication options include OAuth 2.0, personal access tokens, OAuth 1.0a (deprecated), and basic HTTP auth
  • There is detailed documentation available for all the REST endpoints

The REST API allows you to interact with most Jira resources and perform operations like creating issues, updating fields, managing users, etc.

GraphQL API

Jira also offers a GraphQL API through the Atlassian GraphQL Gateway. Some key aspects of the GraphQL API:

  • It allows accessing data across multiple Atlassian products, including Jira
  • Provides more flexibility in querying exactly the data you need
  • Uses a single request to fetch related data, rather than multiple REST calls
  • Has a strongly typed schema that defines available queries and mutations
  • Requires specifying the exact fields you want returned

Does the Jira Data Center API have webhooks?

Yes, the official Jira Data Center API does support webhooks. Here are the key points about webhooks in Jira Data Center:

Webhook Support

  • Jira Data Center supports both incoming and outgoing webhooks.
  • Webhooks have been supported since Jira 5.2.

Types of Events

You can subscribe to a wide variety of events in Jira webhooks, including:

  • Issue events: created, updated, deleted, worklog changed
  • Issue link events: created, deleted
  • Comment events: created, updated, deleted
  • Project events: created, updated, deleted
  • Version events: released, unreleased, created, moved, updated, deleted/merged
  • Sprint events: created, deleted, updated, started, closed
  • Board events: created, updated, deleted, configuration changed
  • Feature enabled/disabled events for various Jira features

Key Considerations

  1. You can restrict webhook events to a subset of issues using JQL queries.

  2. Webhooks can be registered via the Jira administration console or the Jira REST API.

  3. Jira supports both incoming webhooks (listening for requests from other applications) and outgoing webhooks (making requests to other applications).

  4. Webhooks in Jira are triggered by specific events but have a global context, even if you specify conditions in the Filter/JQL.

  5. Having too many webhooks or webhooks with slow/heavy filters may impact Jira's performance.

Best Practices

  • Use JQL queries carefully to filter webhook events, as some custom fields can take multiple seconds to query.
  • Consider using Jira Automation for more advanced webhook scenarios.
  • Monitor the impact of webhooks on performance using log entries like "JqlEventMatcher_SLOW" in the Jira logs.

In summary, Jira Data Center offers robust webhook support with a wide range of event types to subscribe to, allowing for flexible integrations with other systems and applications.

Rate Limits and other limitations

Based on the search results provided, here are the key points about API rate limits for Jira Data Center:

Rate Limiting Implementation

  • Jira implements rate limiting to ensure services remain reliable and responsive for customers [2].
  • Rate limiting is not used to differentiate service levels between customer types or apps [2].

Rate Limit Budgets

  • API requests are associated with different cost budgets depending on the authentication type [2]:
    • User: for requests made by an end user
    • App: for requests made by an app without direct user interaction
    • App + user: for requests made by an app associated with a user interaction
    • Anonymous: for requests not associated with a user or app

Rate Limit Details

  • Specific rate limits for Jira Data Center API are not publicly published [2].
  • The rate limiting logic evolves continuously to maximize reliability and performance [2].

Detecting and Handling Rate Limits

  • Apps can detect rate limiting by checking for HTTP 429 status codes [2].
  • Rate limited responses may include headers like Retry-After and X-RateLimit-Reset to indicate when to retry [2].
  • Apps should implement backoff and retry logic to handle rate limits [2].

Best Practices

  • Minimize data requested by using caching, pagination, and specifying required fields [2].
  • Design apps to scale by using "App + user" budgets rather than a single "App" budget [2].
  • Spread out requests to lower peak usage [2].
  • For large ad-hoc processing, consider scheduling during off-peak hours [2].

Key Considerations

  • The exact rate limits are not published and may change [2].
  • Rate limiting is based on concurrency and cost, not just request count [2].
  • Apps should be designed to handle rate limiting gracefully [2].

In summary, while specific rate limits are not published for Jira Data Center, the API does implement rate limiting. Apps need to be designed to detect and handle rate limits appropriately to ensure reliable operation.

Latest API Version

Based on the search results provided, here is the answer to your question:

The most recent version of the Jira Data Center API is version 2.

Key points to consider:

  • The current API version is 2, as stated in the URI Structure section: "The current API version is 2" [2][4].

  • There is also a symbolic version called "latest" which resolves to the latest version supported by a given Jira instance [2][4].

  • The most recent release of Jira Software Data Center is version 9.17, released on June 26, 2024 [3].

  • The REST API documentation for the latest Jira Data Center version (9.14.0 as of the search results) can be found at https://docs.atlassian.com/software/jira/docs/api/REST/9.14.0/.

Best practices:

  • When making API calls, you can use either the specific version number (2) or the "latest" symbolic version in the URI path.

  • Always check the documentation for the specific Jira version you are working with, as there may be slight differences between versions.

  • Keep track of the latest Jira releases and updates to ensure compatibility with your integrations and apps [3].

How to get a Jira Data Center developer account and API Keys?

  1. Obtain a Data Center developer license:

    • Free Data Center developer licenses are available to billing and technical contacts of active commercial Data Center licenses in my.atlassian.com.
    • Click "View Developer License" in the Actions menu of your Data Center license to access the developer license.

  2. Set up a Jira Data Center instance:

    • Install Jira Data Center on your own infrastructure using the developer license.
    • Data Center products are hosted by the customer, not Atlassian.

  3. Create a user account:

    • Create a normal user account in your Jira Data Center instance.
    • Provide the necessary project access and permissions for API usage.

  4. Generate an API token:

    • Log in to your Atlassian account associated with the Jira instance.
    • Go to https://id.atlassian.com/manage/api-tokens and generate a new API token.

  5. Use the API token for authentication:

    • Use the API token in place of a password when making API requests.
    • For example, with curl: 
      curl -v https://your-instance.atlassian.net --user [email protected]:your-api-token

  6. Access the REST APIs:

    • Refer to the Jira Data Center REST API documentation for available endpoints and methods.
    • Use the API token for authentication when making requests.

What can you do with the Jira Data Center API?

Based on the search results provided, here is a list of data models that can be interacted with using the Jira Data Center API, along with what is possible for each:

Issues

  • Create, read, update, and delete issues
  • Search for issues using JQL
  • Add comments to issues
  • Update issue fields
  • Transition issues through workflows
  • Add and remove issue links
  • Add and manage attachments

Projects

  • Create, read, update, and delete projects
  • Manage project categories
  • Configure project settings and schemes

Users

  • Create, read, update, and delete user accounts
  • Manage user groups and permissions
  • Update user preferences

Workflows

  • Create and manage workflows
  • Configure workflow schemes
  • Transition issues through workflow statuses

Fields and Screens

  • Create and manage custom fields
  • Configure field configurations and screens
  • Set up field contexts and options

Filters and Dashboards

  • Create and manage saved filters
  • Build and configure dashboards

Versions and Components

  • Manage project versions
  • Create and update project components

Permissions and Security

  • Configure permission schemes
  • Manage issue security levels
  • Set up security schemes

Service Desks (for Jira Service Management)

  • Create and manage service desks
  • Configure request types
  • Manage SLAs

Boards (for Jira Software)

  • Create and configure Scrum and Kanban boards
  • Manage sprints
  • Configure board settings

Reporting

  • Generate various reports on issues, projects, etc.
  • Access metrics and statistics

Administration

  • Configure global settings
  • Manage add-ons and integrations
  • Access system information

The API allows for comprehensive interaction with most aspects of Jira, enabling developers to automate processes, integrate with other systems, and build custom functionality on top of Jira Data Center.

Ship integrations on autopilot

Get Demo
Resources
DocumentationIntegrationsAPI Integration GuidesBlogChangelogPricingSupport
Legal
Terms of ServicePrivacy PolicyGoogle API
© 2024 Playbook Software Inc.