Add enhanced_search_issues API for Jira Cloud using new search/jql endpoint #2326

skumar36-atlassian · 2025-03-18T08:22:03Z

Overview

This PR introduces two new functions for Jira Cloud:

`enhanced_search_issues`

Leverages the new search/jql REST endpoint with nextPageToken-based pagination.
Replaces the deprecated search API endpoints (GET/POST /rest/api/3/search).
Allows for either limited or complete fetching of results (when maxResults is set to False).
Atlassian will remove support for the old search API on May 1, 2025.

`approximate_issue_count`

Calls the search/approximate-count API to retrieve an approximate count of issues matching a given JQL query.
Returns either an integer count or the full JSON response based on the json_result flag.
Available only for Jira Cloud.

Changes

`enhanced_search_issues`

✅ Implements nextPageToken-based pagination.
✅ Fetches all results if maxResults evaluates to False; otherwise, it fetches up to the specified limit.

`approximate_issue_count`

✅ Retrieves an approximate count of issues for a given JQL query.
✅ Returns either an integer count or the full JSON response.

💡 Both functions are decorated with @cloud_api to ensure they are only used on Jira Cloud.
🔹 Jira Cloud users will use these new APIs.
🔹 Jira Server/Data Center users remain unaffected and will continue using the existing APIs.

Deprecation Fix: Explicit Sphinx Configuration

Read the Docs has deprecated automatic detection of Sphinx/MkDocs configuration files, leading to potential build failures. To ensure stable and predictable documentation builds, we have explicitly defined the sphinx.configuration key in .readthedocs.yaml.
For more details, refer to the official announcement: Read the Docs Deprecation Notice

Testing & Limitations

Manual Testing

✔️ Validated against a Jira Cloud instance.

Unit Tests

⚠️ Unit tests for these cloud-specific endpoints could not be fully implemented due to challenges in configuring the test environment for Jira Cloud.
🔹 Further work is needed to establish a dedicated Jira Cloud test setup.

Migration & Impact

🚨 Breaking Change

Atlassian has already deprecated the old search API endpoints, with support ending on May 1, 2025.
Jira Cloud users must migrate to using enhanced_search_issues and approximate_issue_count to ensure continued compatibility.
Jira Server/Data Center users are not affected and can continue using the existing APIs.

Additional Context

This update aligns with Atlassian's deprecation roadmap, improving performance and reliability for Jira Cloud users.
For any questions or further clarification, please refer to the discussion thread on this PR or reach out via our developer community forum.

Please review the changes and let me know if any further modifications are required. 🚀

Introduce a new function enhanced_search_issues that calls the new search/jql REST endpoint, replacing the deprecated search API for Jira Cloud. This update leverages nextPageToken-based pagination for improved performance and prepares the library for the removal of the old endpoints (GET/POST /rest/api/3/search) effective May 1, 2025. BREAKING CHANGE: Jira Cloud users should migrate to enhanced_search_issues as the old search_issues endpoint is deprecated.

for more information, see https://pre-commit.ci

wblondel · 2025-03-18T12:50:47Z

Hey @skumar36-atlassian , thank you for your work!!

I'm not a maintainer of this repo but it seems a label is missing on this PR, preventing a check from passing. Could you add one? Options are bug, enhancement, major, minor, patch, skip-changelog.

devactivity-app · 2025-03-18T12:50:50Z

@wblondel, ⭐3 XP earned, 🏆First Comment Added completed!
Contribute more to raise your XP/Level, complete challenges for extra achievements! [Sign up for personal dashboard]

skumar36-atlassian · 2025-03-18T13:45:31Z

/label enhancement

skumar36-atlassian · 2025-03-18T13:47:44Z

Hey @skumar36-atlassian , thank you for your work!!

I'm not a maintainer of this repo but it seems a label is missing on this PR, preventing a check from passing. Could you add one? Options are bug, enhancement, major, minor, patch, skip-changelog.

Yes, I have tried to add /label enhancement as a comment and update the title with enhancement: keyword, also I am not seeing any option to update it to enhancement. @ssbarnea can you help here?

skumar36-atlassian · 2025-03-18T14:03:58Z

@ssbarnea , @adehad , @studioj I don't have the necessary permissions to add labels to this PR. Could someone please add the "enhancement" label? Let me know if anything else is needed.

skumar36-atlassian · 2025-03-28T05:12:02Z

@jeffgeorge , @wblondel ,@adehad, @ssbarnea any updates?

wblondel · 2025-03-28T06:11:46Z

I cannot do anything, I am not a maintainer.

studioj · 2025-03-28T12:35:51Z

Heyhey, I'll have a look this evening... Let's see if we can get this on the main line.
I'm a maintainer but we're having release issues where @ssbarnea will need to help out with. He's the owner on pypi

devactivity-app · 2025-03-28T12:35:54Z

@studioj, ⭐3 XP earned, 🏆First Comment Added completed, 💪Level 3 achieved!
Contribute more to raise your XP/Level, complete challenges for extra achievements! [Sign up for personal dashboard]

devactivity-app · 2025-03-29T22:11:21Z

@studioj, ⭐3 XP earned, 🏆First Code Review Done completed, 💪Level 3 achieved!
Contribute more to raise your XP/Level, complete challenges for extra achievements! [Sign up for personal dashboard]

skumar36-atlassian · 2025-03-30T08:47:37Z

Thanks @studioj for your approval.
@ssbarnea can you please approve and release this.

devactivity-app · 2025-03-30T12:53:43Z

Pull Request Summary by devActivity

Metrics

Achievements

@ssbarnea
Earned XP: 15⭐
Check Your Progress
@skumar36-atlassian
Earned XP: 10⭐
Sign up here to check your progress
@wblondel
Earned XP: 4⭐
Completed Challenges: 🏆First Comment Added
Sign up here to check your progress
@studioj
Earned XP: 6⭐
Completed Challenges: 🏆First Comment Added, 🏆First Code Review Done
Sign up here to check your progress

skumar36-atlassian and others added 5 commits March 17, 2025 13:32

Remove extra lines

6c6b5f6

[pre-commit.ci] auto fixes from pre-commit.com hooks

796d88f

for more information, see https://pre-commit.ci

Resolved merge conflicts

56d8f46

Update the message

a4371cc

skumar36-atlassian requested a review from a team as a code owner March 18, 2025 08:22

skumar36-atlassian requested a review from ssbarnea March 18, 2025 08:22

skumar36-atlassian had a problem deploying to ack March 18, 2025 08:22 — with GitHub Actions Failure

skumar36-atlassian had a problem deploying to check March 18, 2025 08:25 — with GitHub Actions Failure

Remove print statement

f57acdc

skumar36-atlassian had a problem deploying to ack March 18, 2025 08:32 — with GitHub Actions Failure

skumar36-atlassian had a problem deploying to check March 18, 2025 08:36 — with GitHub Actions Failure

skumar36-atlassian mentioned this pull request Mar 18, 2025

Upcoming Deprecation of Jira Cloud Search APIs #1940

Open

Fix: Add explicit Sphinx configuration for ReadTheDocs

d16b39f

skumar36-atlassian had a problem deploying to ack March 18, 2025 10:54 — with GitHub Actions Failure

[pre-commit.ci] auto fixes from pre-commit.com hooks

c60ec1c

for more information, see https://pre-commit.ci

pre-commit-ci bot had a problem deploying to ack March 18, 2025 10:54 Failure

pre-commit-ci bot had a problem deploying to check March 18, 2025 10:57 Failure

pre-commit-ci bot had a problem deploying to check March 18, 2025 12:56 Failure

Merge branch 'main' into feature/enhanced-search-api

bed65a6

skumar36-atlassian had a problem deploying to ack March 18, 2025 13:24 — with GitHub Actions Failure

skumar36-atlassian temporarily deployed to check March 18, 2025 13:28 — with GitHub Actions Inactive

studioj added the enhancement label Mar 28, 2025

studioj temporarily deployed to ack March 28, 2025 12:38 — with GitHub Actions Inactive

studioj self-assigned this Mar 28, 2025

studioj approved these changes Mar 29, 2025

View reviewed changes

ssbarnea approved these changes Mar 30, 2025

View reviewed changes

ssbarnea merged commit 46943ba into pycontribs:main Mar 30, 2025
15 of 16 checks passed

ssbarnea changed the title ~~enhancement: Add enhanced_search_issues API for Jira Cloud using new search/jql endpoint~~ Add enhanced_search_issues API for Jira Cloud using new search/jql endpoint Mar 30, 2025

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add enhanced_search_issues API for Jira Cloud using new search/jql endpoint #2326

Add enhanced_search_issues API for Jira Cloud using new search/jql endpoint #2326

skumar36-atlassian commented Mar 18, 2025 •

edited

Loading

wblondel commented Mar 18, 2025 •

edited

Loading

devactivity-app bot commented Mar 18, 2025

skumar36-atlassian commented Mar 18, 2025

skumar36-atlassian commented Mar 18, 2025

skumar36-atlassian commented Mar 18, 2025

skumar36-atlassian commented Mar 28, 2025

wblondel commented Mar 28, 2025

studioj commented Mar 28, 2025

devactivity-app bot commented Mar 28, 2025

devactivity-app bot commented Mar 29, 2025

skumar36-atlassian commented Mar 30, 2025

devactivity-app bot commented Mar 30, 2025

Add enhanced_search_issues API for Jira Cloud using new search/jql endpoint #2326

Add enhanced_search_issues API for Jira Cloud using new search/jql endpoint #2326

Conversation

skumar36-atlassian commented Mar 18, 2025 • edited Loading

Overview

enhanced_search_issues

approximate_issue_count

Changes

enhanced_search_issues

approximate_issue_count

Deprecation Fix: Explicit Sphinx Configuration

Testing & Limitations

Manual Testing

Unit Tests

Migration & Impact

Additional Context

wblondel commented Mar 18, 2025 • edited Loading

devactivity-app bot commented Mar 18, 2025

skumar36-atlassian commented Mar 18, 2025

skumar36-atlassian commented Mar 18, 2025

skumar36-atlassian commented Mar 18, 2025

skumar36-atlassian commented Mar 28, 2025

wblondel commented Mar 28, 2025

studioj commented Mar 28, 2025

devactivity-app bot commented Mar 28, 2025

devactivity-app bot commented Mar 29, 2025

skumar36-atlassian commented Mar 30, 2025

devactivity-app bot commented Mar 30, 2025

Pull Request Summary by devActivity

Metrics

Achievements

skumar36-atlassian commented Mar 18, 2025 •

edited

Loading

`enhanced_search_issues`

`approximate_issue_count`

`enhanced_search_issues`

`approximate_issue_count`

wblondel commented Mar 18, 2025 •

edited

Loading