Change notice - Required encoding of some characters used in REST API calls

As part of our continued focus on the security of our Cloud platform, and a recent Tomcat update we’ve made, we’re introducing changes that’ll require the encoding of some characters used in REST API calls. We’ll make these changes on the 1st of April next year (2019) , giving developers and consumers of Jira Cloud APIs six months to make any necessary changes. These changes are not related to other GDPR-related API updates we’re currently making.

See official change notice

1 Like

@rwhitbeck, is there a timeline when these changes will be available for testing/preview?

Hi @ademoss, you bring up an excellent question. Since this is a configuration change to Tomcat this will pose more difficult to get out to you for testing before the date of change on April 1st. I’ve been talking with the team on how we can get this out sooner for you to test but we’re still not sure how best to do it. Unlike a feature release where we can target specific instances a configuration change happens at a container level and isn’t easily targeted to a few instances.

At this time the only advice I have is to run through your code and ensure that you are url encoding your parameters that you are sending back to us. Perhaps add some more tests to catch for this going forward.

When you said “encoding request parameters”, do you mean by that both path and query params?

I’m asking, because I am little big confused. Please have a look at the below example.
Endpoint to get issue details requires issueKey as path parameter:
And as far as I know all issue keys have hyphen in it, and hyphen according to the depreciation note should be encoded. allows: -, [, ] characters in the path

Sorry @awieczorek, I don’t know the answer, I’ve asked the team for clarification. BTW, please refer to the official change notice and not my comment above as the source of truth. I may have said parameters by mistake. I’ll let you know what the team says.

Hi Ralph, did the developers get back to you about this?

Both Java and Javascript’s built-in URL parsing/encoding functions do not encode the hyphen character in either the path part of a URL.

Thanks for the bump, yes they did … here is the reply I got:

I just checked with Jira Dev, and as you probably already assumed, all use of those characters in urls need to be encoded, both the path and query as site names themselves can contain these characters. Think the approach needs to be that they ensure everything coming out of their application is url encoded

Further clarification that something in the hostname is fine, but the url is not - I find that a little confusing

I’ll pass your concern on to the devs regarding the url.

@rwhitbeck thanks for the update, so to confirm, we need to send requests to instead of which we can’t do using the built-in language features of Javascript or Java as they do not escape the “unreserved” characters (which the - is) as listed in


@rwhitbeck can you confirm that we’re unable to rely solely on the default URL encoding tools provided by both Java and Javascript for this change because Atlassian are now expecting non-standard encoding of URLs?

Sorry I got a reply that the - character shouldn’t be in the list of unsupported unencoded characters.

I’ll make sure the change notice gets updated to reflect this clarification.

Thanks for bringing it to our attention.

1 Like