Jira Service Management API Essential Guide

What type of API does Jira Service Management provide?

Jira Service Management primarily uses a REST API. Here are the key points:

REST API

• Jira Service Management provides a REST API for developers to integrate with and administrators to script configuration interactions.

• The REST API uses JSON as its communication format and standard HTTP methods like GET, PUT, POST, and DELETE.

• The structure of the REST URIs follows this pattern: http://host:port/context/rest/servicedeskapi/resource-name.

Authentication

• The Jira Service Management REST API uses the same authentication methods as Jira, with OAuth and HTTP Basic Auth (when using SSL) being the preferred methods.

• Other supported authentication methods include HTTP Cookies and Trusted Applications.

API Features

• The API supports pagination to conserve server resources and limit response size.

• Resource expansion is used to simplify API responses, allowing clients to request specific entities to be included in the response.

• The API provides access to various resources such as service desks, request types, organizations, and more.

GraphQL API

While not specific to Jira Service Management, it's worth noting that Atlassian also provides a GraphQL API for accessing data across various Atlassian products, including Jira. However, the primary API for Jira Service Management is the REST API.

Summary

Jira Service Management primarily offers a REST API, which provides a comprehensive set of endpoints for interacting with various aspects of the service. This API follows REST principles, uses JSON for data exchange, and supports standard HTTP methods. It also includes features like pagination and resource expansion to optimize API usage.

Does the Jira Service Management API have webhooks?

Yes, the official Jira Service Management API does have webhooks. Here are the key points about webhooks in Jira Service Management:

Webhook Availability

• Webhooks are available in Jira Service Management and can be used to notify external applications when certain events occur in Jira.

Types of Events

You can subscribe to various types of events in Jira Service Management webhooks, including:

1. Issue-related events:

   • Issue created (jira:issue_created)
   • Issue updated (jira:issue_updated)
   • Issue deleted (jira:issue_deleted)
   • Worklog changed (jira:worklog_updated)

2. Comment events:

   • Comment created (comment_created)
   • Comment updated (comment_updated)
   • Comment deleted (comment_deleted)

3. Project events:

   • Project created (project_created)
   • Project updated (project_updated)
   • Project deleted (project_deleted)

4. Version events:

   • Version released (jira:version_released)
   • Version unreleased (jira:version_unreleased)
   • Version created (jira:version_created)
   • Version moved (jira:version_moved)
   • Version updated (jira:version_updated)
   • Version deleted/merged (jira:version_deleted)

5. Sprint events:

   • Sprint created (sprint_created)
   • Sprint deleted (sprint_deleted)
   • Sprint updated (sprint_updated)
   • Sprint started (sprint_started)
   • Sprint closed (sprint_closed)

6. Board events:

   • Board created (board_created)
   • Board updated (board_updated)
   • Board deleted (board_deleted)
   • Board configuration changed (board_configuration_changed)

Webhook Configuration

When configuring a webhook in Jira Service Management, you need to provide:

1. A name for the webhook
2. The URL where the callback should be sent (HTTPS only for cloud instances)
3. The scope of the webhook (e.g., all issues or a specific set of issues defined by JQL)
4. The events to post to the URL (all events or a specific set of events)

Best Practices

• Use HTTPS URLs for security, especially in cloud instances.
• Consider using JQL to limit the scope of webhooks to specific issues or projects.
• Be aware of the authentication requirements for webhooks, especially when using the v2 version of the REST API.
• Implement proper error handling and timeout management in your webhook receiver.

By using webhooks, you can create powerful integrations between Jira Service Management and external systems, allowing for real-time updates and automated workflows based on events occurring in Jira.

Rate Limits and other limitations

Here are the key points about API rate limits for the Jira Service Management API:

Rate Limit Implementation

• Rate limiting is implemented by tracking the cost of processing requests against various cost budgets [2].

• Requests are associated with different cost budgets based on authentication type:

  • User budget: for end user requests
  • App budget: for app requests without user interaction
  • App + user budget: for app requests associated with user interaction
  • Anonymous budget: for unauthenticated requests [2]

Rate Limit Details

• Specific rate limits are not published, as the computation logic evolves continuously [2].

• Rate limits are designed to ensure reliability and responsiveness, not to differentiate service levels [2].

Handling Rate Limits

• Apps should detect rate limits by checking for HTTP 429 status codes [2].

• When rate limited, apps should:

  1. Back off and retry after a delay
  2. Use exponential backoff, doubling the delay after each 429 response
  3. Apply jitter to retry delays to avoid thundering herd problems [2]

• Response headers provide information on rate limits:

  • Retry-After: Seconds to wait before retrying
  • X-RateLimit-Reset: Timestamp when request can be retried
  • X-RateLimit-NearLimit: Indicates <20% of budget remains [2]

Best Practices

• Consolidate requests where possible to reduce overhead [2]
• Use bulk operations when available [2]
• Only request necessary data using field/property specifications [2]
• Use pagination to limit result sets [2]
• Consider caching to reduce API calls [2]
• Use webhooks for updates to lower request volume [2]

Key Considerations

• Design apps to scale with number of users by using "App + user" budgets [2]
• Be cautious with multi-threading, as high concurrency may trigger rate limits [2]
• Do not attempt to circumvent rate limits through concurrency [2]

By following these guidelines and implementing proper rate limit handling, developers can build robust apps that work effectively within Jira's rate limiting system.

Latest API Version

Based on the search results, I can provide the following information about the most recent version of the Jira Service Management API:

The most recent version of the Jira Service Management API appears to be associated with Jira Service Management 5.17. This can be inferred from the release notes information provided in the search results.

Key points to consider:

1. Jira Service Management follows a versioning scheme where the major version number (e.g., 5.x.x) indicates significant updates, while minor versions (e.g., 5.17.x) represent smaller updates and bug fixes.

2. The latest version mentioned in the search results is Jira Service Management 5.17, which suggests that this is likely the most recent version of the API as well.

3. It's important to note that Atlassian frequently releases updates for their products, so the version number may change over time.

4. For the most up-to-date information on API versions, it's recommended to check the official Atlassian documentation or developer resources.

5. The Jira Service Management REST API does not typically have separate version numbers. Instead, it is usually associated with the version of the Jira Service Management product itself.

Best practices:

1. Always refer to the most recent documentation when working with the API, as features and endpoints may change between versions.

2. When integrating with a specific Jira Service Management instance, it's a good practice to check the version of that instance to ensure compatibility with your integration.

3. If you need to work with a specific version of the API, consider using the appropriate documentation for that version, which can often be found in Atlassian's archived documentation.

4. Keep in mind that Atlassian may deprecate older API versions over time, so it's important to stay informed about any announcements regarding API changes or deprecations.

How to get a Jira Service Management developer account and API Keys?

To get a developer account for Jira Service Management and create an API integration, here are the key steps:

1. Sign up for a Jira Service Management account

• Go to the Atlassian website and sign up for a Jira Service Management Cloud account if you don't already have one.

2. Set up an API integration

• A default API integration is provided with your Jira Service Management account.
• However, it's recommended to add a separate API integration for each monitoring system you want to integrate.

To set up a new API integration:

1. Go to the Integrations section in Jira Service Management
2. Select "Add integration"
3. Optionally select an assignee team
4. Click "Continue"
5. Copy the request URL provided
6. Turn on the integration

3. Generate API token

• Create a normal user account in Jira Service Management (there are no special "service accounts")
• Generate an API token for this user account

4. Use the API

• Use the Jira Service Management REST API to access and update entities like requests and organizations
• The endpoint URL will be in the format: https://<your-domain>.atlassian.net/rest/api/3/
• Use the API token for authentication when making API calls

What can you do with the Jira Service Management API?

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

Service Desk

• Get service desk details
• Add customers to a service desk
• Remove customers from a service desk
• Get all customers of a service desk
• Get queues for a service desk
• Create and manage request types for a service desk

Request

• Create customer requests
• Get request details
• Get all requests for a service desk
• Add and remove request participants
• Add comments to requests
• Get request status
• Transition requests through workflows
• Add attachments to requests

Organization

• Create and manage organizations
• Add and remove users from organizations
• Associate organizations with service desks

Customer

• Create customers
• Get customer details
• Get requests raised by a customer

Queue

• Get queue details
• Get issues in a queue

Knowledgebase

• Get knowledge base articles
• Search knowledge base

Request Type

• Get request type details
• Get fields for a request type

Approval

• Get approval details
• Approve or decline approvals

Comment

• Add comments to requests
• Get comments on a request

Attachment

• Add attachments to requests
• Get attachments on a request

SLA

• Get SLA information for requests

The API allows performing CRUD operations on most of these data models, as well as retrieving associated data and performing key actions like transitioning requests or managing approvals. The exact capabilities may vary slightly between Jira Service Management Cloud and Server versions.