Add First-Class Support for the HTTP QUERY Method (RFC 10008)

[otaviojava]

This proposal introduces first-class support for the HTTP QUERY method, as defined by RFC 10008, into Jakarta REST.

Server API

This would be based on a single annotation:

@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
@HttpMethod("QUERY")
public @interface QUERY {
}

Usage:

@Path("/users")
public class UserResource {

    @QUERY
    @Consumes(MediaType.APPLICATION_JSON)
    @Produces(MediaType.APPLICATION_JSON)
    public List<User> search(UserFilter filter) {
        return service.search(filter);
    }
}

Client API

Provide convenience methods for invoking QUERY requests without requiring generic method invocation.

Example:

client.target(uri)
      .request()
      .query(Entity.json(filter));

or equivalent API design determined by the specification committee.

Specification Goal

Define the semantics of QUERY according to RFC 10008:

• Safe
• Idempotent
• Allows request content
• Intended for retrieval and query operations
• Not intended for resource modification

[hantsy]

I have filed #1324

[otaviojava]

I have filed #1324

Thanks, @hantsy, but I'll take a different approach: I'll provide more code details instead of a single link.

If the team agrees, I can move forward with a contribution.

[hantsy]

It seems Servlet has already included HTTP QUERY method in 6.2, jakartaee/servlet#1069.

[mkarg]

It seems Servlet has already included HTTP QUERY method in 6.2, jakartaee/servlet#1069.

IMHO this is irrelevant for Jakarta REST, as (a) Jakarta REST is not dependend of Servlet, (b) Jakarta REST is a REST API while Servlet is a HTTP API.

[mkarg]

If the team agrees, I can move forward with a contribution.

Actually there is no majority in team for adopting QUERY yet. This might change in future, but currently most committers did not vote, which does not imply agreement.

[sandeshkuldharme1]

Hi @otaviojava ,

I would love to work on this!

The proposal is clear. I can handle:

1. Server API: Adding @QUERY annotation and updating jakarta.ws.rs.HttpMethod.QUERY.
2. Client API: Adding query(Entity) convenience methods to SyncInvoker, AsyncInvoker, and RxInvoker.
3. Spec & TCK: Updating the specification text for RFC 10008 semantics and writing TCK compliance tests.

Could you please assign this issue to me? I can start working on a draft PR for initial feedback right away.

Thanks!