What is changing?
Instead of returning all comments for GET /rest/api/[2 3 latest]/issue/{issueIdOrKey} and jira:issue_deleted webhook events, we will return the latest comments in ascending order, up to a limit of 5,000.
The payload currently includes maxResults and total. After the change, total will still show the total comments count, but maxResults will indicate the maximum number of comments returned, i.e. <= 5000. This way, consumers will be able to figure out if the comments are fully returned by comparing maxResults and total.
In addition, a new self fields will be added to the payload to identify the API that allows fetching all comments with pagination, i.e. /rest/api/[2 3 latest]/issue/{issueIdOrKey}/comment.
The change of response is changed from:
"comment": {
"comments": [
...comments
],
"maxResults": 5555,
"total": 5555,
"startAt": 0
}
to:
"comment": {
"comments": [
...comments
],
"maxResults": 5000, // consumers can tell if it's fully loaded by comparing maxResults vs total
"total": 5555,
"startAt": 0,
"self": "TENANT-DOMAIN/rest/api/[2|3|latest]/issue/10098/comment" //new
}
Why is it changing?
- Whilst the vast majority of our issues are associated with a reasonable amount of comments (see the comment section for more reference), there are still some issues with a large number of comments, e.g. 246k. When consumers are querying those issues through /rest/api/[2 3 latest]/issue/{issueIdOrKey}, it tries to serialise and return all comments which caused 5xx response.
- jira:issue_deletedWebHook API shares the same shape as issue REST API, so this change applies to jira:issue_deleted WebHook for consistency purpose as well as 5xx reason.
What do I need to do?
If your app does not depend on the payloads returned by the GET /rest/api/[2 3 latest]/issue/{issueIdOrKey} and jira:issue_deleted webhook events, no changes are required, otherwise check its parsing of the payload will handle the extra self field.
If your app depends on the comments content returned in GET /rest/api/[2 3 latest]/issue/{issueIdOrKey} or jira:issue_deleted webhook events.
If your app only needs to know about the total count of the comments on issues, you can still use total in the comments response and no changes to your app are necessary.
If you know none of the issues retrieved by your app would have more than the newly imposed limit of the number of comments or that your app does not need to access more than the newly imposed limit of the number of the most recent issue comments, no changes to your app are necessary.
If your app needs to know if the quantity of comments returned by the GET /rest/api/[2 3 latest]/issue/{issueIdOrKey} resource or jira:issue_deleted webhook event has been limited, use the maxResults and total response fields to determine this (pseudo code: hasMoreComments = total > maxResults).
If your app needs to obtain more than the newly imposed limit of the number of comments returned from the GET /rest/api/[2 3 latest]/issue/{issueIdOrKey} resource, switch to the GET /rest/api/[2 3 latest]/issue/{issueIdOrKey}/comment resource to retrieve the comments using paginated requests. As part of this, it may also be prudent to modify your request to GET /rest/api/[2 3 latest]/issue/{issueIdOrKey} so comments are not unnecessarily returned.
It will no longer be possible for apps to acquire all issue comments when processingjira:issue_deleted a webhook event for an issue with over the newly imposed limit of the number of comments. Please notify us if this will negatively impact your app.
By when do I need to do it?
We have chosen a deprecation period of 3 months rather than the usual six months for the following reasons:
- Our analysis indicates the impact will be negligible. For instance, no issues deleted in the most recent two months have had a number of comments exceeding the newly imposed limit. Most issues have far fewer comments than the limit being introduced.
- The changes result in significant customer benefits due to improvements to reliability and performance.
- A simple migration guide exists for the use cases we believe to be significant.
Timeline:
- Early December, 2020: Changes will be released to the Jira and Confluence Cloud Vendor First program.
- Mid January 2021: Changes will be rolled out to all remaining Jira tenants.