Programmatic Server APIs for producing RESTful APIs

[hantsy]

Spring WebMvc and WebFlux provide flexible APIs for developers to build Web APIs by annotation controllers or functional programming APIs.

@Bean
public RouterFunction<ServerResponse> routes(PostHandler postHandler, BlogProperties blogProperties) {
    return route(GET("/info"), (req) -> ok().body(blogProperties))
            .andRoute(GET("/posts"), postHandler::all)
            .andRoute(POST("/posts"), postHandler::create)
            .andRoute(GET("/posts/{id}"), postHandler::get)
            .andRoute(PUT("/posts/{id}"), postHandler::update)
            .andRoute(DELETE("/posts/{id}"), postHandler::delete);
}

Every request handler is something like a Function<Request, Response>.

In Jakarta Rest, we can add a method to Application to accept route definitions or declare a CDI bean via @Produces.

• Define route definitions by functional APIs.
• Add filter globally or interceptor to some endpoints.
• Allow to handle exceptions globally(to handle the exceptions not handled in the routes).

See:

• Spring Mvc RouterFunction: https://github.com/spring-projects/spring-framework/blob/main/spring-webmvc/src/main/java/org/springframework/web/servlet/function/RouterFunction.java
• Vertx Route: https://vertx.io/docs/vertx-web/java/

[mkarg]

In my opinion, such an API completely contradicts the basic idea of the previous JAX-RS API. I don't see any advantage over the previous API. Can you give us a few advantages of what is supposed to be better with the new API than with the previous one?

[hantsy]

The annotation-based resources class and programmatic APIs should share a common code base.

For developers, it provides two options for building RESTful APIs, more flexible.

• The classic annotation declarations
• The programmatic APIs are a good match for functional programming which assembles the codes with pipelines(filter, transform, collect, etc operations), esp, the new function/supplier/consumer functions introduced in Java 8 and the new Reactive Streams.

As https://github.com/hantsy/spring-puzzles/tree/master/programming-models, spring provides several options when archiving the same purpose.

And as I saw in some ppt of demonstrating Jakarta EE future, if we provide more Bootstrap APIs for specs, such as Messaging, etc. (CDI, REST already included Bootstrap API), and a root JakartaApplication, functional programming is easier to assemble application functionality.

[spericas]

This is introducing a whole new API flavor that isn't declarative or traditional IoC. Although useful for some applications, it probably does not belong in Jakarta REST.

[hantsy]

@spericas Check the API design of Spring WebFlux. I hope annotation resources and route functions share the same handling process in the background.

It is NOT a whole new thing.

[spericas]

@spericas Check the API design of Spring WebFlux. I hope annotation resources and route functions share the same handling process in the background.

It is NOT a whole new thing.

I disagree. The moment your handlers are of the formFunction<Request, Response> everything changes: there's no longer param injection etc. You can surely build a Jakarta REST implementation on top of such a core, but that's not how current implementations are built. There are many other frameworks like Spring that support this alternate style (e.g. Helidon) but standardizing an API for a new flavor like that is outside of our scope IMO.

[hantsy]

here's no longer param injection etc

We can get the raw data(headers, params, path variables) directly in the request object and modify the response data before sending it to the client.

A programmatic API tries to remove the use of annotations, using functional API to assemble the process manually.

[jansupol]

Jersey does support a proprietary programmatic API for building resources. Maybe if other vendors do support similar API, it would make sense to standardize it.

[hantsy]

@jansupol It looks good, but the programming style is a little old, I would like to embrace the Java 8 Function/Supplier/Consumer to simplify the APIs like the one provided in Spring.

1. Add a routeConfig method in the Application or declare a RouteConfig like a CDI bean as the entry. Assemble the method's route paths(nested paths aka subresources)/filter/exception handling.
2. Add the similar function (ServerRequest)-> ServerResponse to build the resource logic freely.