search

jakartaee / rest

Jakarta RESTful Web Services
Other
361 stars 117 forks source link

Support for RFC 6570 "URI Template" #1152

Open mkarg opened 1 year ago

mkarg commented 1 year ago

As proposed by @jansupol in a recent Jersey discussion the adoption of RFC 6570 "URI Template" could clarify some ambiguities in Jakarta REST's current definition of when to / when not to percent-encode template parameter values. Due to that, I hereby propose the mandatory support of RFC 6570 for Jakarta REST 4.0.

mkarg commented 1 year ago

@chkal @jansupol @jamezp @arjantijms @spericas WDYT?

jamezp commented 1 year ago

I'd be a +1 as I think this makes sense.

jansupol commented 1 year ago

The RFC fits perfectly with the UriBuilder functionality and putting it to the Spec requirement seems natural to me.

jansupol commented 1 year ago

UriBuilder mandates throwing IllegalArgumentException for a missing template argument which is in contradiction to the RFC which skips missing arguments: Section 3.2.1:

A variable that is undefined (Section 2.3) has no value and is ignored by the expansion process. If all of the variables in an expression are undefined, then the expression's expansion is the empty string.

jansupol commented 1 year ago

Depending on which part of Uri the template is used for, the template behavior changes

For Uri, the path does not percent-encode reserved characters such as the exclamation mark "!" The RFC default template {var} should percent-encode the exclamation mark, whereas other types of a template, such as (path) {/var} or reserved expansion template {+var} do not percent-encode reserved characters (exclamation mark).

The query part, on the other hand, percent-encode the reserved characters.

Hence, the template's default behavior behaves or does not behave as the default template as described in Section 3.2.2 of the RFC and it should be clearly described by the UriBuilder javadoc in the case of the RFC adoption.