Jira Cloud API breaking behavior changes without contract stability

[Michal Jarnot]

Hello Atlassian team 👋
I have run into repeated breaking behavior changes in the Jira Cloud API without any obvious contract/versioning signal, and it is causing avoidable failures in our integration.

Most recently, I hit cases where request shapes that worked previously started failing unless fields were sent explicitly as `null` instead of being omitted. This changed runtime behavior in a way that broke our existing client logic even though the integration had been working before.

This kind of change is difficult for integrators because:
- it breaks production workflows unexpectedly
- it is not obvious from the previous API behavior
- it forces emergency client patches for what appears to be a server-side contract shift

What I need from Atlassian:
1. please avoid silent breaking changes in Jira Cloud API request/response behavior 😊
2. if behavior must change, please communicate it clearly and ahead of time
3. please document whether fields must be omitted vs explicitly set to `null`
4. please confirm the expected contract for optional and nullable fields across Jira Cloud endpoints

Concrete example:
- issue comments / issue update flows started behaving differently depending on whether optional fields were omitted or explicitly sent as `null`
- this required code changes on our side for behavior that had previously worked

Please let me know:
- whether this is an intentional API contract change
- where such changes are announced
- what stability guarantees I should rely on for Jira Cloud integration

Thanks 🤗

Michal Jarnot

[Arkadiusz Wroblewski]

Hello and Welcome @Michal Jarnot 

I would split that on 3 Ways:

• experimental endpoint → change without notice is possible
• non-experimental endpoint → silent runtime contract shifts are hard to justify unless they fall under Atlassian’s explicit exceptions or are documented/deprecated properly
• nullable vs omitted → I do not see a single global rule published for Jira Cloud; that tends to be endpoint-specific, which is exactly why these cases need clearer docs or a bug confirmation.

Thats two places where you can track changes:

Atlassian developer changelog

Jira Cloud Platform changelog

Atlassian REST API policy

[Michal Jarnot]

I do not see a single global rule published for Jira Cloud; that tends to be endpoint-specific, which is exactly why these cases need clearer docs or a bug confirmation.

Is this text LLM generated?

[Arkadiusz Wroblewski]

@Michal Jarnot 

LOL...

Whether you like the wording or not is secondary here. I’m also not a native speaker, so sorry if I did not phrase it in the easiest way. What I was trying to explain is that Atlassian does not publicly define or regulate nullable vs. omitted behavior in one clear global rule. The real point here is the technical one.

My point was quite specific:

1. experimental endpoints can change with less stability guarantees
2. non-experimental endpoints should not silently change contract behavior unless that is covered by Atlassian’s policy or documented properly
3. for the nullable vs omitted behavior, I do not see a single global Jira Cloud rule that clearly settles this across endpoints

That is exactly why I linked the changelogs and REST API policy.

So if you think any part of that is incorrect, feel free to point to the specific statement. 

[Michal Jarnot]

Does that mean that I am correct and Atlassian is unknowingly introducing breaking changes or is there something that I missed?

I only use ~15 endpoints from the enormous API that Atlassian provides but still I had to rewrite one tool yesterday and then another today. I can't imagine what people and companies who rely on Atlassian run into if they use more of the API services.

[Arkadiusz Wroblewski]

@Michal Jarnot 

If you want my honest opinion? Yes, sometimes.

A layoff of 1,600 people at once (Specialist which was working deep on Code from Years), shifting that work onto others, and the general push toward “vibe coding” can absolutely have an effect.

And I think some of that has been visible over roughly the last 18 months. To me, that is also part of why Atlassian is now introducing the new seasonal release approach:
https://community.atlassian.com/forums/Jira-Cloud-Admins-articles/Coming-soon-Jira-seasonal-releases/ba-p/3177320

They have faced quite a bit of backlash in recent months because of unexpected changes.

PS: What annoys me most is how huge the ecosystem has become. It is sometimes really difficult to keep up with all the changes, and scrolling through endless release notes is not exactly enjoyable. The platform is developing constantly, so it is easy to miss something important.

[Michal Jarnot]

JIRA API error (400): We could not find the sprint

OK at this point I have to be doing something wrong. There is no way that the system is this broken. 🤣