Search After Write with Search And Reconcile

In this doc, we explore how to effectively utilize the eventual consistency API and understand the nuances of consistency in read-after-write scenarios. We guide you through the search and reconcile patterns to help you manage and interpret the data from the endpoints:

GET (/rest/api/{2|3|latest}/search/jql)

POST (/rest/api/{2|3|latest}/search/jql)

The API doesn’t provide read-after-write consistency by default. That is, after a write operation is performed, subsequent search operations using the API without the reconcileIssues parameter may return stale or outdated data instead of the most recent updates for some time.

The delay might vary from a few seconds to minutes, depending on the operation. The majority of modifications are shown within seconds. Operations that impact numerous issues, such as issue reordering or bulk editing, may require more time to appear in search.

More about reconciliation

In order to eliminate the problem of stale or outdated data, the user can use the reconcileIssues parameter in the request body to get consistent results immediately after updating the issues.

• API can accept a maximum of 50 reconcile issues.
• When utilizing the reconcileIssues pattern, consistency is ensured only for the specified issues.

Achieving high consistency with reconcileIssues

Using Rest API

1. The user creates, edits, or bulk edits the issue.

2. The response object contains the issue ID.

   Important Note — When editing the issue, make sure to send the returnIssue query parameter as true as per the API to get the response body, which will contain the issue ID.

   1
   2
   {
     "id": "10000",
     "key": "ED-24",
     ...
     }
   }
   

3. To obtain consistent results for the above issue ids, you can pass the issue ids in reconcileIssues parameter.

   1
   2
   {
     "jql":"project in (FOO, BAR)",
     "fields": "key, id",
     "reconcileIssues": [10000]
   }
   

4. The response will contain the reconciled issues if they satisfy the JQL and the nextPageToken.

   1
   2
   {
       "issues": [
           {
               "expand": "...",
               "id": "10068",
               "self": "https://example-jira.atlassian.net/rest/api/latest/issue/10068",
               "key": "FOO-1"
           },
           {
               "expand": "...",
               "id": "10067",
               "self": "https://example-jira.atlassian.net/rest/api/latest/issue/10067",
               "key": "BAR-2"
           },
           {
               "expand": "...",
               "id": "10000",
               "self": "https://example-jira.atlassian.net/rest/api/latest/issue/10000",
               "key": "BAR-1"
           }
       ],
       "nextPageToken": "CAEaAggD"
   }
   

Using Webhooks

1. App subscribes to webhook events
2. A new issue event arrives, which contains the issue ID.

   1
   2
   {
       "issue": {
           "id": "10000",
           ...
           "fields":[
               ...
           ]
           ...
           "updated": "2024-08-19T11:40:30.010+0200",
       }
   }
   

3. To obtain consistent results for the above issue ids, you can pass the issue ids in reconcileIssues parameter.

   1
   2
   {
     "jql":"project in (FOO, BAR)",
     "fields": "key, id",
     "reconcileIssues": [10000]
   }
   

4. The response will contain the reconciled issues if they satisfy the JQL and the nextPageToken.

   1
   2
   {
       "issues": [
           {
               "expand": "...",
               "id": "10068",
               "self": "https://example-jira.atlassian.net/rest/api/latest/issue/10068",
               "key": "FOO-1"
           },
           {
               "expand": "...",
               "id": "10067",
               "self": "https://example-jira.atlassian.net/rest/api/latest/issue/10067",
               "key": "BAR-2"
           },
           {
               "expand": "...",
               "id": "10000",
               "self": "https://example-jira.atlassian.net/rest/api/latest/issue/10000",
               "key": "BAR-1"
           }
       ],
       "nextPageToken": "CAEaAggD"
   }
   

For additional information about the API please visit here