Resource Matching Using @QueryParams

[shelley-jean-baker]

Why is @QueryParam not calculated in the resource matching?

The JAX-RS specification seems to indicate that the entire URI should be used for matching resource methods:

A request is matched to the corresponding resource method or sub-resource method by comparing the nor-
malized request URI (see Section 3.7.1), the media type of any request entity, and the requested response
entity format to the metadata annotations on the resource classes and their methods

and:

Prior to matching, request URIs are normalized by following the rules for case, path segment, and percent encoding normalization described in section 6.2.2 of RFC 3986. The normalized request URI MUST be reflected in the URIs obtained from an injected UriInfo.

The UriInfo includes query as an identifying part of the URI, which is consistent with RFC 3986, which clearly includes the query as an identifying component of the resource:

URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ]

The query component contains non-hierarchical data that, along with
data in the path component (Section 3.3), serves to identify a
resource within the scope of the URI's scheme and naming authority
(if any).

Given this, I would expect to be able to define two resources similar to the following, as their resource identifiers are uniquely identified by the query component, which is specified as a metadata annotation on the resource method definition:

@GET
@Path("test")
public List<MyResource> filterMyResources() {
    ...
}

@GET
@Path("test")
@QueryParam("filter")
public List<MyResource> filterMyResources(@QueryParam("filter") String filter) {
    ...
}

However, attempts to do this results in an error when starting up the application, similar to the following:

A resource model has ambiguous (sub-)resource method for HTTP method GET and input mime-types as defined by"@consumes" and "@produces" annotations [...] These two methods produces and consumes exactly the same mime-types and therefore their invocation as a resource methods will always fail.

Why does Jersey not take the query params into account when identifying resources?

By comparison, this can be implemented successfully in Spring as follows:

@GetMapping(value = "/test", produces = MediaType.APPLICATION_JSON_VALUE)
public List<MyResource> getAllMyResources() {
    ...
}

@GetMapping(value = "/test", produces = MediaType.APPLICATION_JSON_VALUE, params = "filter")
public List<MyResource> filterMyResources(@RequestParam("filter") String filter) {
    ...
}

Note that I haven't tested any other JAX-RS implementations, but have used this feature in Spring in the past and was quite surprised it was not available in Jersey.

[jansupol]

The ambiguity of the Resource endpoints is determined by the Algorithm in Section 3.7 of the Jakarta REST Spec. This matching algorithm does not take the query parameter into account.

The workaround this is very simple, just add an extra @Path to the resource method and the client request URI path.

[shelley-jean-baker]

Thanks. The paragraph description of Section 3.7.2 and Section 3.7.1 mention only the "Request URI" which includes the query param per RFC 3986 which it references. However, I do see the algorithm in Section 3.7.2 that you mentioned which only includes the "request URI path" and also realize that the Servlet spec's definition of "Request URI" does not agree with RFC 3986's definition either as it, too, separates out the query component of the URI.

The workaround this is very simple, just add an extra @Path to the resource method and the client request URI path.

I'm fully aware of this option, but changing my URI design because the JAX-RS spec doesn't properly support this situation is not ideal. The other workaround is to define one resource method for the path that conditionally varies the resource representation returned based on the provided query params. This sacrifices the readability of the internal implementation, but at least allows for the desired URI design to remain.