Making the Intentions Explicit with "JAX-RPC" over JAX-RS

JAX-RS stands for: "Jakarta RESTful Web Services" (former: "Java API for RESTful Web Services") and was intended to expose Java classes in resource oriented style like e.g. GET /accounts/12345.

APIs based on the HATEOAS principle are self descriptive and programming language independent, but require a significant re-thinking how Java methods are mapped to URIs. A mixture of REST-style and RPC style, where resources and methods are exposed at the same time, is hard to understand and to maintain.

However, JAX-RS can be easily "misused" to directly expose methods in 1:1 fashion without any rethinking.

Instead of the "resources" context path, a the JAX-RS application is exposed via the rpc path:

@ApplicationPath("rpc")
public class JAXRSConfiguration extends Application {}    

After setting the expectations, all the classes and methods are exposed with their name and in the @PATH POST method:

@Consumes(MediaType.APPLICATION_JSON)
@Produces(MediaType.APPLICATION_JSON)    
@Path("workshops")
public class Workshops {

    @POST
    @Path("newWorkshop")
    public JsonObject newWorkshop(JsonObject input) {
    //...
    }

    @POST
    @Path("deleteWorkshop")
    public JsonObject deleteWorkshop(JsonObject input) {
    //...
    }

    @POST
    @Path("getRecentWorkshops")
    public JsonObject getRecentWorkshops(JsonObject input) {
    //...
    }

    @POST
    @Path("changeWorkshopName")
    public JsonObject changeWorkshopName(JsonObject input) {
    //...
    }
}

HTTP POST is neither "safe", nor "idempotent" so it qualifies to the exposure of all Java methods.

Now, e.g. the deleteWorkshop method can be invoked via: curl -d'{}' -i -XPOST -H'Content-Type: application/json' (...)[APP_NAME]/rpc/workshops/deleteWorkshop

This approach is not a best practice rather than application of the "Principle of Least Surprise".

See you at Web, MicroProfile and Java EE Workshops at Munich Airport, Terminal 2 or Virtual Dedicated Workshops / consulting. Is Munich's airport too far? Learn from home: airhacks.io.