Getting started

Three minutes to serve a @Path resource over HTTP with Cassini standalone. One complete Maven project, one bootstrap — the standard SeBootstrap of the REST 4.0 spec. Every snippet below is copy-pasteable and tested end to end against the released 0.2.x artifacts.

Looking for the batteries-included experience (CDI, config, packaging, dev mode)? Use the Vidocq runtime: vidocq create --name my-api -x cassini-rest — see the runtime getting-started guide. This page covers Cassini standalone, without the runtime.

Prerequisites

Java 25 (Temurin recommended) — check with java -version
Maven 3.9+ — check with mvn -version

The project

A single, complete pom.xml — nothing else to configure:

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>com.example</groupId>
    <artifactId>hello-cassini</artifactId>
    <version>1.0.0-SNAPSHOT</version>

    <properties>
        <maven.compiler.release>25</maven.compiler.release>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    </properties>

    <dependencies>
        <dependency>
            <groupId>jakarta.ws.rs</groupId>
            <artifactId>jakarta.ws.rs-api</artifactId>
            <version>4.0.0</version>
        </dependency>
        <dependency>
            <groupId>io.vidocq.cassini</groupId>
            <artifactId>cassini-core</artifactId>
            <version>0.2.0</version>
        </dependency>
        <!-- reference transport, embeds the Chappe HTTP server -->
        <dependency>
            <groupId>io.vidocq.cassini</groupId>
            <artifactId>cassini-chappe</artifactId>
            <version>0.2.0</version>
            <scope>runtime</scope>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.codehaus.mojo</groupId>
                <artifactId>exec-maven-plugin</artifactId>
                <version>3.5.0</version>
                <configuration>
                    <executable>java</executable>
                    <arguments>
                        <argument>-classpath</argument>
                        <classpath/>
                        <argument>com.example.hello.Main</argument>
                    </arguments>
                </configuration>
            </plugin>
        </plugins>
    </build>
</project>

For a zero-external-dependency deployment, swap cassini-chappe for cassini-jdk-http: it relies solely on the JDK’s com.sun.net.httpserver.

First resource

src/main/java/com/example/hello/HelloResource.java:

package com.example.hello;

import jakarta.ws.rs.Consumes;
import jakarta.ws.rs.DefaultValue;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.POST;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.PathParam;
import jakarta.ws.rs.Produces;
import jakarta.ws.rs.QueryParam;
import jakarta.ws.rs.core.MediaType;
import jakarta.ws.rs.core.Response;

@Path("/hello")
public class HelloResource {

    @GET
    @Produces(MediaType.TEXT_PLAIN)
    public String hello(@QueryParam("name") @DefaultValue("world") String name) {
        return "Hello, " + name + "!";
    }

    @GET
    @Path("/{id}")
    @Produces(MediaType.APPLICATION_JSON)
    public Item getItem(@PathParam("id") long id) {
        return new Item(id, "Article #" + id);
    }

    @POST
    @Consumes(MediaType.APPLICATION_JSON)
    @Produces(MediaType.APPLICATION_JSON)
    public Response createItem(Item item) {
        return Response.status(Response.Status.CREATED).entity(item).build();
    }

    public record Item(long id, String label) {}
}

JSON marshalling of the Item record works out of the box — cassini-core embeds Champollion (JSON-B).

Bootstrap

src/main/java/com/example/hello/Main.java — the standard SeBootstrap of the REST 4.0 spec. The transport (ChappeRuntimeDelegate) is discovered via ServiceLoader: application code references no transport-specific symbol.

package com.example.hello;

import java.util.Set;

import jakarta.ws.rs.SeBootstrap;
import jakarta.ws.rs.core.Application;

public class Main {

    public static void main(String[] args) throws Exception {
        var config = SeBootstrap.Configuration.builder()
            .host("0.0.0.0")
            .port(8080)
            .rootPath("/")
            .build();

        SeBootstrap.start(MyApplication.class, config)
            .thenAccept(instance -> System.out.println(
                "Cassini started at http://localhost:" + instance.configuration().port()))
            .toCompletableFuture()
            .join();

        Thread.currentThread().join();
    }

    public static class MyApplication extends Application {
        @Override public Set<Class<?>> getClasses() {
            return Set.of(HelloResource.class);
        }
    }
}

Build and run

mvn -q compile exec:exec

exec:exec forks a real JVM with the project classpath (configured once in the pom above) — the transport and the CassiniStack implementation are discovered via ServiceLoader. The in-process exec:java variant is not supported: its isolating class loader breaks that discovery.

In another terminal:

$ curl "http://localhost:8080/hello?name=Cassini"
Hello, Cassini!

$ curl http://localhost:8080/hello/42
{"id":42,"label":"Article #42"}

$ curl -X POST http://localhost:8080/hello \
       -H 'Content-Type: application/json' \
       -d '{"id":1,"label":"first"}'
{"id":1,"label":"first"}

Stop the server with Ctrl+C.

Going further

CDI-managed resources (@Inject, scopes): the streamlined path is the Vidocq runtime — it wires Vauban, the annotation processors and the packaging for you. The standalone wiring (Vauban container, cassini-cdi-vauban, build-time bean index) is demonstrated in the cassini-examples-vauban module.
Embedding Cassini in an existing Chappe server (composite handlers, static files + API): see the CassiniStack SPI in Usage and the cassini-examples modules.
Usage — sub-resources, providers, async, SSE · Concepts · TCK status