Jira Software Server API Essential Guide

What type of API does Jira Software Server provide?

Jira Software Server primarily uses a REST API. The REST API uses JSON as its communication format and standard HTTP methods like GET, PUT, POST and DELETE. The URI structure for Jira's REST API is http://host:port/context/rest/api-name/api-version/resource-name. There are two main API names available: auth for authentication-related operations and api for everything else. The current API version is 2, but there's also a symbolic version called latest which resolves to the latest supported version. Authentication methods for the REST API include OAuth and HTTP basic authentication (when using SSL).

Jira also provides webhooks, which are user-defined callbacks over HTTP specific to the Jira REST API. While Jira previously had SOAP and XML-RPC APIs, these were removed in Jira 7.0 for Server. Atlassian encourages using the REST APIs instead.

There is also an Atlassian platform GraphQL API that can be used to access Jira data, among other Atlassian products.

Does the Jira Software Server API have webhooks?

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

Webhook Support

• Jira Server 5.2 and later versions support webhooks.

Types of Events

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

1. Issue events:

   • Created
   • Updated
   • Deleted
   • Worklog changed

2. Issue link events:

   • Created
   • Deleted

3. Comment events:

   • Created
   • Updated
   • Deleted

4. Project events:

   • Created
   • Updated
   • Deleted

5. Version events:

   • Released
   • Unreleased
   • Created
   • Moved
   • Updated
   • Deleted/Merged

6. Sprint events:

   • Created
   • Deleted
   • Updated
   • Started
   • Closed

7. Board events:

   • Created
   • Updated
   • Deleted
   • Configuration changed

8. Feature enabled/disabled events for various Jira features

Webhook Configuration

When registering a webhook, you need to provide:

1. A name for the webhook
2. The URL where the callback should be sent
3. The scope of the webhook (all issues or a limited set specified by JQL)
4. The events to post to the URL (all events or a specific set of events)

Registering Webhooks

You can register webhooks using:

1. The Jira administration console
2. The Jira REST API (requires Jira Administrators global permission)

Best Practices

• When using JQL to filter events, be cautious with custom fields that may take long to query, as this can impact performance.
• For specific state changes, it's better to filter on the receiving side rather than in the JQL clause to avoid potential issues with frequently changing fields.

Limitations

There are some known limitations in older versions of Jira (5.2.x and earlier) regarding JQL usage with webhooks, so it's important to check the specific version documentation if using an older Jira instance.

Rate Limits and other limitations

Based on the search results, here are the key points about API rate limits for Jira Software Server:

Rate Limits

• There are no published specific rate limits for the Jira Software Server API.

• The rate limiting logic is evolving continuously to maximize reliability and performance for customers.

• While exact limits are not published, there are some general guidelines:

  • Jira limits the rate of REST API requests to ensure services remain reliable and responsive.

  • Rate limiting is not used to differentiate service levels for different customers or apps.

Key Considerations

• Rate limiting is based on concurrency and cost of requests.

• Different types of authentication (user, app, app+user, anonymous) have separate cost budgets.

• Minimizing the amount of data requested can help avoid rate limiting.

• Using features like caching, pagination, and webhooks can reduce API request volume.

• For large-scale processing, consider scheduling during off-peak hours.

Best Practices

• Design apps to scale by using "App + user" cost budgets rather than a single "App" budget.

• Implement backoff and retry logic to handle potential rate limiting.

• Avoid excessive concurrency or multi-threading, as it may trigger rate limiting.

• Use context parameters and efficient querying to minimize necessary API calls.

• For bulk operations, anticipate and account for potential rate limiting.

While specific limits are not published, developers should design their integrations to be efficient and implement proper error handling for potential rate limiting responses. The Jira API may return 429 status codes if rate limits are exceeded.

Latest API Version

Based on the search results, here are the key points regarding the most recent version of the Jira Software Server API:

1. The current API version is 2. This is mentioned in the documentation for Jira Server REST API.

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

3. For Jira Server 8.3.4 specifically, which is the version mentioned in the question, the REST API documentation is available at https://docs.atlassian.com/software/jira/docs/api/REST/8.3.4/.

4. The REST API version does not necessarily correspond directly to the Jira Software version number. Even for newer Jira versions like 8.3.4, the API version is still 2.

5. When making API calls, you can use either the numeric version (2) or "latest" in the URL path, for example:

   http://host:port/context/rest/api/2/resource-name
   

   or

   http://host:port/context/rest/api/latest/resource-name
   

6. There is a WADL document available that contains documentation for each resource in the Jira REST API.

In summary, the most recent version of the Jira Software Server API is version 2, regardless of the Jira Software version being used (within reason - very old versions may differ). When integrating with a Jira Server installation, you can use API version 2 or the "latest" symbolic version in your API calls.

How to get a Jira Software Server developer account and API Keys?

Here are the key steps to get a developer account for Jira Software Server to create an API integration:

1. Create a Jira user account:

   • Create a dedicated user account in your Jira instance to use for API integrations (e.g. [email protected]).
   • Give this account the necessary permissions to perform the API actions you need (e.g. Jira User, Jira Software User, etc.).

2. Generate an API token:

   • Log in as the API service account you created.
   • Go to your Atlassian account settings and generate an API token.
   • This token will be used for authentication instead of a password.

3. Set up authentication:

   • Use either Basic Authentication or OAuth for API requests.
   • For Basic Auth, use the API service account username and API token.
   • OAuth is recommended for better security in production environments.

4. Make API requests:

   • Use the Jira REST API to interact with Jira programmatically.
   • Authenticate requests using the API token or OAuth credentials.

Key points to consider:

• The API service account will consume a Jira license.
• Generate separate tokens for dev/test and production environments.
• Rotate tokens periodically for security.
• Use a dedicated service account rather than a personal account to avoid issues if an employee leaves.

Best practices:

• Use OAuth for better security in production.
• Limit the permissions of the API service account to only what's needed.
• Store credentials securely and don't hardcode them in source control.
• Monitor and audit API usage.

By following these steps, you can set up a dedicated developer account to securely integrate with the Jira Software Server API. Let me know if you need any clarification or have additional questions!

What can you do with the Jira Software Server API?

Based on the search results, here are the key data models you can interact with using the Jira Software Server API, along with what is possible for each:

Issues

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

Projects

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

Users and Groups

• Create, read, update, and delete users
• Manage user groups and permissions
• Handle user authentication

Workflows

• Create, read, update, and delete workflows
• Manage workflow schemes

Custom Fields

• Create, read, update, and delete custom fields
• Configure custom field options

Filters and Dashboards

• Create, read, update, and delete filters
• Manage dashboards

Versions and Components

• Create, read, update, and delete versions
• Manage components within projects

Permissions and Security

• Manage permission schemes
• Configure issue security levels

Attachments

• Upload and retrieve attachments

Comments

• Add, edit, and delete comments on issues

Agile Features (Jira Software specific)

• Manage sprints and boards
• Work with epics

Service Desk Features (Jira Service Management specific)

• Handle customer requests
• Manage service desk queues

It's important to note that while there are some differences between Jira Server and Jira Data Center, the APIs are generally the same for both products. The main differences are in cluster-specific APIs for Data Center. Additionally, Atlassian is focusing more on cloud development, but Data Center continues to receive investment and has an active roadmap.