How to test against the data center api

[Mike Bowler]

I'm the author of an open source tool to extract metrics reports from Jira. It used to be that I could test against the Cloud API and reasonably expect that my code would also work on Data Center (and Server). That's no longer true with the recent changes to the search API. Cloud now only supports v3 and Data Centre only supports v2, which means I have different code for each.

Is there a test instance of Data Center that I can run my code against? How are others handling this?

[Matteo Vecchiato]

Hi @Mike Bowler

Welcome to Atlassian community.

You can install Jira on you own local computer, following this tutorial: https://confluence.atlassian.com/adminjiraserver/install-a-jira-data-center-trial-1044784650.html 

API in cloud used to be very similar to Data Center version, but then it started change and there have been several deprecations.

I hope it helps.

Regards 

[Mike Bowler]

This trial would be a good short term fix (30 day trial) but doesn't address the longer term need to keep testing my code. I'm still wondering what others are doing.

[Sunny Ape]

Hello @Mike Bowler 

You've made a small mistake in your thinking; Jira Cloud does not 'only' support a v3 API, it has a v2 API too, which is being developed in parallel. The difference between the two is that the v3 API mandates the use of ADF for all requests and responses; apart from that, they are the same.

There is nothing anyone can do about the gradual diversion of endpoints between the v2 API of Jira Cloud and Jira DC, as development of the DC product is slowly coming to an end now that it's been marked for end-of-life. However, if you want to have your own private DC instance for testing against in the meanwhile, apply for a Developer's license and run an instance in Docker etc.

[Mike Bowler]

Over the last few weeks, Atlassian has very publicly stated that they have started turning off some of the v2 search API's in cloud. Yes, most of v2 still works but the search API's are a critical part of what I need to test.

[Sunny Ape]

I think you have totally misinterpreted the deprecation announcements from Atlassian

Almost 12 months ago they said they would start turning off two particular JQL search APIs in Jira Cloud in mid 2025 and replacing them with two other JQL search APIs. Those changes would apply to both the v2 AND v3 versions of the same Issue Search endpoints, equally. Atlassian did not , under any circumstances that I know of, say they were turning off v2 endpoints and replacing them with nothing or with v3 endpoints only.

If you refer to the v3 Issue Search endpoints documentation you will see the changes made are identical to the changes made the corresponding v2 Issue Search endpoints.

Next, refer to this Blog Post that describes the rationale behind the changes and how to be prepared. The post also says that the changes apply to both the v2 AND v3 versions of the same endpoints.

Lastly, refer to the Change Notice that also says that both the v2 AND v3 versions of the same endpoints are changing equally.

[Mike Bowler]

From one of the pages you just linked: "There is a deprecation period of 6 months, and these endpoints will be removed after May 1, 2025."

Then I've received several pop-ups in the Jira UI over the last few weeks warning about those API's going away.

I would love to believe that these API's will remain but that's not what I'm reading. It seems very clear that on cloud, the endpoint /rest/api/2/search is going away, to be replaced with a similar v3 API. On DataCenter however, that v2 API is the only option because DataCenter doesn't support v3.

So we're back to the same problem. When searching, the code that works for DataCenter does not work on Cloud and vice versa. Anyone writing code that needs to work with both, now requires two different test environments.

[Sunny Ape]

From one of the pages you just linked: "There is a deprecation period of 6 months, and these endpoints will be removed after May 1, 2025."

Yeah,,, followed by a long and detailed description of the endpoints that are replacing those deprecated endpoints. I don't understand how you not able to find that exact information right there, in the Change Notice. Just click the More Details drop-down and it all pours out!

It seems very clear that on cloud, the endpoint /rest/api/2/search is going away, to be replaced with a similar v3 API.

Sorry buddy, and I hate to say it to you this way, but... you're completely, totally and utterly wrong!

Yes, the /rest/api/2/search endpoint IS going away, but it absolutely IS NOT being replaced by a "similar v3 API"... it is being replaced the similar v2 API endpoint... /rest/api/2/search/jql , exactly as stated in the Change Notice documentation.

I know this to be completely, totally and utterly true as I personally changed all my code over to the new v2 Search for Issues using JQL advanced endpoint more than 6 months ago, as have a multitude of other developers, and the new endpoint works perfectly.

When searching, the code that works for Data Center does not work on Cloud and vice versa.

Sorry buddy, and I hate to say it to you this way, but... of course some code that works on Cloud doesn't work on Data Center and vice versa!

The Cloud and DC / Server REST APIs have been gradually diverging for more than a decade and this is just another one of dozens of endpoints that now are no longer a like-for-like match, or simply don't exist at all on the other instance type.

I too develop for both Cloud and DC environments. When I make a connection to a Jira instance, I just start with an anonymous query to the Get Jira instance info endpoint to know what type of Jira I'm interacting with, then within my code I just adjust where needed for the different endpoint requirements.

Anyone writing code that needs to work with both, now requires two different test environments

And, what's the problem? Hundreds, possibly thousands of Jira devs do just that, every day of the week, and twice on Sunday.

If you absolutely must build reliably for Jira DC and must have a permanent read / write instance all for yourself, then you must find an Organisation who will patronise you and give you a Developer License from their active licence. If not, just install a local instance of Jira DC, fill it with all the test data you need, then let it turn into a read only instance after 30 days.

Anyhow, the whole discussion of the deprecation of some Issue Search endpoints is months old now and, IMHO, been done to death.... you can find dozens of threads on the exact same topic with a Google search if you care to research further.

That being the case, I consider this discussion complete now, and I'll leave you to your musings.

Have fun, code brother ;)