Migration Guide: Updating JQL Search Endpoints

Overview

This guide provides detailed instructions for migrating from deprecated JQL search endpoints to the new endpoints introduced in the Jira REST API. The migration involves replacing old GET and POST endpoints used for JQL searches with updated endpoints. This change is necessary to maintain seamless functionality and compatibility with future API enhancements.

Identify and Update Deprecated Endpoints

Review your existing integration code to locate any usage of the deprecated endpoints and replace them with the new parameters:

GET Requests:

• DEPRECATED GET /rest/api/{2|3|latest}/search → [link]

• NEW GET /rest/api/{2|3|latest}/search/jql → [link]

POST Requests:

• DEPRECATED POST /rest/api/{2|3|latest}/search → [link]

• NEW POST /rest/api/{2|3|latest}/search/jql → [link]

Update GET Requests

Example Migration

Adjust your query string to include any new parameters required by the updated endpoint. For example, if your current GET request is:

DEPRECATED Local Jira with URL GET

.../rest/api/3/search?jql=summary ~ '{searchTerm}'

Please update it to:

NEW GET method

.../rest/api/3/search/jql?jql=summary ~ '{searchTerm}'&fields=*all

This example demonstrates how to append additional parameters (e.g., fields=*all) to ensure complete results are returned.

Update POST Requests

Example Migration

Changes to your POST request are made in a similar way. For example, if your current POST request text is as follows:

DEPRECATED POST endpoint

.../rest/api/3/search

Please update it to:

NEW POST method

.../rest/api/3/search/jql

Updated POST Request Body Example:

{
  "jql": "summary ~ '{searchTerm}'",
  "maxResults": 10,
  "fields": [
    "*all"
  ]
}

The updated example body specifies the JQL query, the maximum number of results, and the fields to be retrieved.

Pagination

In case you are using those data source in combination with a paginated data source you should also follow this guide.

Once you have made all changes, please verify that the responses contain the expected data to ensure that the migration was successful.