enhancement: Add enhanced_search_issues API for Jira Cloud using new search/jql endpoint

[skumar36-atlassian]

Overview

This PR introduces two new functions for Jira Cloud:

1. enhanced_search_issues:
   This function leverages the new search/jql REST endpoint with nextPageToken-based pagination. It is designed to replace the deprecated search API endpoints (GET/POST /rest/api/3/search), which Atlassian has already deprecated and will remove support for on May 1, 2025. The function allows for either limited or complete fetching of results (when maxResults is set to false).

2. approximate_issue_count:
   This new function calls the search/approximate-count API to retrieve an approximate count of issues matching a given JQL query. This endpoint is available only for Jira Cloud and is essential for users who need a quick estimation of matching issues.

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:
  • Returns either an integer count or the full JSON response based on the json_result flag.
• Both functions are decorated with @cloud_api to ensure they are only used on Jira Cloud.
• The new implementations are intended for Jira Cloud users, while Jira Server/Data Center users will continue using the existing APIs.

Testing & Limitations

• Manual Testing: I have manually validated these changes against my Jira Cloud instance.
• Unit Tests: Due to difficulties in configuring our testing environment for Jira Cloud (the existing tests are designed primarily for Data Center setups), I was not able to write complete unit tests for these cloud-specific endpoints. Further work is needed to establish a dedicated Jira Cloud test environment.

Migration & Impact

• Breaking Change:
  Atlassian has already deprecated the old search API endpoints, and support for these endpoints will be removed 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 by these changes and can continue using the existing APIs.

Additional Context

• This update aligns with Atlassian's decision to deprecate and eventually remove support for the old search endpoints, aiming for a more reliable and performant Jira Cloud experience.
• 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.

[devactivity-app]

@skumar36-atlassian, ⭐3 XP earned, 🏆First Pull Request Pushed completed!
Contribute more to raise your XP/Level, complete challenges for extra achievements! [Sign up for personal dashboard]

[github-actions]

Label error. Requires exactly 1 of: bug, enhancement, major, minor, patch, skip-changelog. Found: feature

[devactivity-app]

Pull Request Summary by devActivity

Metrics

Achievements

• @skumar36-atlassian
  Earned XP: 5⭐
  Completed Challenges: 🏆First Pull Request Pushed
  Sign up here to check your progress

[skumar36-atlassian]

Will be creating a new PR with a new label as it's failing the label check.

[devactivity-app]

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