Interface as Contract for Client/Server

[hantsy]

Spring 6.x introduces a declarative HTTP interface that can be the contract between the client and server.

https://docs.spring.io/spring-framework/reference/integration/rest-clients.html#rest-http-interface

Jakarta EE has a sister project MP which includes MP Rest Client to declare the Client via interface.

Is it possible to adopt the MP Rest client into REST spec?

1. Allow developers to declare an interface as the contract of the Client/Server side.

    @Path("/posts")
    public interface PostResource {
   
        @GET
        @Produces(MediaType.APPLICATION_JSON)
        public Uni<List<Post>> getAllPosts();
   
        @POST
        @Consumes(MediaType.APPLICATION_JSON)
        public Uni<Response> savePost(@Valid Post post);
   
        @Path("{id}")
        @GET
        @Produces(MediaType.APPLICATION_JSON)
        public Uni<Response> getPostById(@PathParam("id") final String id);
   
        @Path("{id}")
        @PUT
        @Consumes(MediaType.APPLICATION_JSON)
        public Uni<Response> updatePost(@PathParam("id") final String id, @Valid Post post);
   
        @DELETE
        @Path("{id}")
        public Uni<Response> delete(@PathParam("id") String id);
    }
   
   

2. On the server side, we need to implement the interface.

   @RequestScoped // declared as a CDI bean
   class PostResourceImple implements PostResource{
   }
   

3. On the client side, use programmatic API to create the Client.

   // A Client Adapter/Factory similar API is based on the Client, to set up the base URL, auth, error handlers, etc.
   PostResource postClient = clientAdapter.create(...)
   

4. When Config spec is stable, also allow configuring the interface Client in config properties(similar to the MP Rest Client does).

   @Inject @RestClient PostResource ...;
   

[mkarg]

Thank you for filing your change request. Can you please briefly outline what the actual benefit for the user would be? I am using a shared interface for client and server since years with 100% pure JAX-RS API and never missed someting in the spec, so I am keen to learn why you want to have that?

[FroMage]

I'm not sure I understand. As far as I know, there's never been any stub/proxy support for REST clients in JAX-RS. That's always been added on top of the spec as part of RESTEasy or MP REST Client.

[FroMage]

The only client I see in the spec is https://jakarta.ee/specifications/restful-ws/4.0/jakarta-restful-ws-spec-4.0#client_api and that's not a proxy/stub model like MP REST Client.

[mkarg]

I'm not sure I understand. As far as I know, there's never been any stub/proxy support for REST clients in JAX-RS. That's always been added on top of the spec as part of RESTEasy or MP REST Client.

So IIUC then the actual core idea of this RFE is to enforce JAX-RS vendors to provide mandatory stub/proxy support? Then I would propose to change the title and description of this RFE to make that clear. Thanks.

[FroMage]

That's how I understood the issue description. Perhaps I'm wrong 🤷

[hantsy]

@FroMage Currently the MP Rest Client supports interface client declaration.

[lasteris]

@hantsy What are you trying to reach ? Did you read this ever ? https://quarkus.io/guides/rest-client

[hantsy]

@lukasj Of course, a big fan of Quarkus since it was born.

[jansupol]

Is it possible to adopt the MP Rest client into REST spec?

Microprofile came as a reaction to a long delay between Java EE 7 and Java EE 8. MP Rest Client is an API built atop JAX-RS, it is an extension of of JAX-RS which should have been a part of JAX-RS, but it is not.

After the transition of Java EE into Eclipse/Jakarta, there was a discussion about merging Microprofile and Jakarta. There also was a discussion about merging MP Rest Client into Jakarta REST.

While it is possible to adopt MP REST Client in Jakarta REST, doing it without the support of MP group would only mean that the MP REST Client spec would be duplicated, and there would be evolution in both Jakarta and MP which would eventually lead to mutual incompatibility and exclusion.

The current state is that implementations of Jakarta REST RestEasy and Jersey do implement also MP REST Client.

[mkarg]

The current state is that implementations of Jakarta REST RestEasy and Jersey do implement also MP REST Client.

As that is the case already, what would be the benefit of supporting this RFE? 🤔

[jansupol]

As that is the case already, what would be the benefit of supporting this RFE? 🤔

It would enrich the possibilities for clients without the MP libs in their environment. It would also allow us to extend the existing feature set. It would provide more consistency between a new functionality in the Jakarta REST Client and the MP Rest Client. It makes sense for the MP Rest Client to be in the Jakarta REST Spec.

There are multiple drawbacks such as that the Jakarta release cycle is slower than MP release cycle, the API namespace might have changed, and people in MP group do not care about Jakarta too much. These drawbacks seem to prevent the MP guys from supporting having the REST Client included in this Spec.

[hantsy]

so I am keen to learn why you want to have that?

1. Make client/server keep consistency in one interface.

2. Make the client calling stupid simple,

    postContract.getAllPosts() // call the interface client method directly which is easier than the `Client` web target request.
   

[hantsy]

There are multiple drawbacks such as that the Jakarta release cycle is slower than MP release cycle,

It is not a bad thing, Jakarta EE can adopt the good part from MP when it becomes mature, such as JWT Auth, and MP REST client here.

[jamezp]

Red Hat is a -1 for bringing MicroProfile Specifications into Jakarta EE Specifications in general. For one this creates fragmentation. There is just no reason to create more fragmentation in the space.

The governance is also different between MicroProfile and Jakarta EE allowing MicroProfile to move faster if desired.