Jakarta RESTful Web Services (Jax-RS) HATEOAS extensions

Introduction

Project in active structuration, not ready for daily use

Check the Wiki for more details!

Goal

Write easily REST APIs with HATEOAS style with JAX-RS in JakartaEE (JavaEE) or Spring environments. Provide server and client support based on JAX-RS principles.

Why

• You can do it manually but it's awful to write and error prone.
• JaxRS only supports natively header links.
• Spring Hateoas is ...meh, only supports Spring Webmvc, doesn't support Jax-RS
• There is no easy client library

Sample code

Target code we want to reach. Shall autodetect annotations.

@Path("products")
@ResourceHateaos
class ProductsController {
    @GET
    @Path("{id}") @ResourceOperationGet
    @Produces(MediaTypeHateoas.APPLICATION_HAL_JSON)
    Product getById(@PathParam("id") String id) {  }

    @GET
    @Path("/") @ResourceOperationList
    @Produces(MediaTypeHateoas.APPLICATION_HAL_JSON)
    ResourceCollection<Product> list(ResourceCollectionFilter filter) {  }

    @POST
    @Path("{id}") @ResourceOperationOther("special")
    @Produces(MediaTypeHateoas.APPLICATION_HAL_JSON)
    Product special() {  }

}

Project provides tooling to do it manually

@GET
@Path("{id}")
@Produces(MediaTypeHateoas.APPLICATION_HAL_JSON)
public Response getById(@PathParam("id") UUID uid, @Context UriInfo uriInfo) {
    Link selfLink = Links.fromUriBuilder("self", uriInfo.getRequestUriBuilder()).rel("self").build();
    Link otherLink = Links.fromUriBuilder("operation1", uriInfo.getRequestUriBuilder()...).build();
    Link embeddedLink = Links.fromUriBuilder("operation2", ()-> getTheContentHere, uriInfo.getRequestUriBuilder()).build();
    return Response.ok(new EntityLinked<>(myobjectByUid, Arrays.asList(selfLink, otherLink, embeddedLink))).build();
}

Stories

Shall produce

• simple links : "_links": { "operation": { "href": "..." }, ... }
• embedded links : "_embedded": { "operation": { _operation_data_ }, ... }
• extensions for OpenAPI documentation when using Eclipse Microprofile OpenAPI

Shall work using the following configurations

• JavaEE 8 / JakartaEE (tests on Wildfly 17 + Resteasy + Jaxb)
• JavaEE 8 / JakartaEE (tests on Wildfly 17 + Resteasy + Jackson)
• Spring(-Boot) + Jackson + Resteasy
• Spring(-Boot) + Jackson + Jersey
• Java 8

Installation

Maven

: publish Maven packages on Github

: publish Maven packages on Maven Central

<dependencies>
    <dependency>
        <!-- core module required -->
        <groupId>net.seij.jakarta-ws-rs-hateoas</groupId>
        <artifactId>core</artifactId>
        <version>0.0.1-SNAPSHOT</version>
    </dependency>
    <dependency>
        <!-- if using jackson -->
        <groupId>net.seij.jakarta-ws-rs-hateoas</groupId>
        <artifactId>jackson</artifactId>
        <version>0.0.1-SNAPSHOT</version>
    </dependency>
</dependencies>

If using Jackson, configure Jackson to add module (Spring-way or JavaEE way)

ObjectMapper om = (new ObjectMapper())
om.addModule(JakartaWsRsHateoasModule.Instance)

Code Samples

• see samples/sample-store-spring

Development installation

• checkout project
• ./mvnw clean install

Documentation in the Wiki for more details!