Comments on JAX-RS 1.0-public-review-draft (April 18, 2008).
Sorry this feedback is after the 2 June deadline. I hope it can still
help.
First off, this looks like a great specification that is well written.
Thanks.
1. Calling @Path values "URI Templates"
I assume the phrase "URI template" is intentionally the same as the
current W3C efforts to write a URI Templates specification (M Hadley
is an editor of both).
A W3C URI template is designed to BUILD a URI from a collection of
parameters
parameters --> URI
JAX-RS @Path values, in contrast, are designed to MATCH a URI and
parse it into parameters
parameters <-- URI
Though these operations are not totally unrelated to each other, they
do operate in different directions. The need different syntaxes. It in
the simplest special cases can only syntax fulfill both purposes. The
current W3C draft says:
"While URI Templates use a notation that is similar to some URI path
matching notations in web frameworks, URI Templates were not designed
for that use case, nor are they appropriate for that purpose."
Consequently, JAX-RS should NOT call @Path values "URI Templates".
A better term might be "URI Path Patterns" -- particular as @Path
values are converted to regular expressions (eg
java.util.regex.Pattern).
2. Template variable regular expression
The regular expression to match a @Path template variable is not quite
right [§3.7.3 Converting URI Templates to Regular Expressions;
footnote 4; page 17].
It currently is
\{([\w-\. ∼]+?)\}
I suggest using
\{([^}]*\}
That is, any string in { }.
There doesn't seem to be any reason to restrict the characters in a
variable name, other than being able to notice when the name ends.
- A hyphen in a character class needs to be the first character,
otherwise it indicates a range.
- A dot does not need to be escaped in a character class.
- There is a space in the character class (before the ~) -- at least
when I cut-n-paste from the PDF. I assume this was not the intention
(though I think all chars, including space, should be allowed,
except }).
- May as well allow an empty string as a name (ie use *, not +).
- I don't think the reluctant qualifier '?' adds anything.
3. MIME type ordering consistency
Page 17 line 20 says: x/y < x/* < */*
Page 18 line 13 says: n/m > n/* > */*
It would be better to pick one convention for the whole doc and adjust
the algorithm descriptions accordingly.
It is probably easiest to change step 3(b) in §3.7.2 on page 17 to say:
(b) Sort M (descending order) as follows:
* The primary key...
* The secondary key...
Sorting of the media types follows the general rule: n/m > n/*
> */*
James Manger