Skip to content

Build a REST API with Quarkus REST

Build and run the posts API in the repository's rest module. This recipe is for developers who know Java and want to follow a Quarkus REST resource through Hibernate Reactive with Panache. It covers this repository's sample rather than generating a different project.

Before you begin

You need Java 25 and a container runtime if you want Quarkus Dev Services to start PostgreSQL. The module sets maven.compiler.release to 25 and uses Quarkus 4.0.0.CR1.

The active datasource configuration sets the database kind to PostgreSQL but does not set a connection URL. Use Dev Services with a container runtime or configure a PostgreSQL connection. Hibernate schema generation is drop-and-create; use a disposable database.

Follow the API structure

The Post entity maps a post to the database. The CreatePostRequest record validates incoming JSON: title cannot be blank and is limited to 100 characters; content cannot be blank.

The PostRepository uses PanacheRepositoryBase<Post, UUID> and returns Mutiny Uni and Multi values. The PostResources class maps the /posts resource to repository operations.

The create handler validates the request, persists a post, and returns a 201 Created response with a Location header:

@POST
@Consumes(MediaType.APPLICATION_JSON)
public Uni<Response> savePost(@Valid CreatePostRequest formData) {
    var post = Post.builder()
            .title(formData.title())
            .content(formData.content())
            .build();
    return this.posts.persist(post)
            .map(saved -> created(URI.create("/posts/" + saved.id)).build());
}

The resource also exposes GET /posts, GET /posts/{id}, PUT /posts/{id}, and DELETE /posts/{id}.

Start the application

  1. Change to the rest module:
cd rest
  1. Start development mode:
./mvnw quarkus:dev

On Windows, run mvnw.cmd quarkus:dev.

Create and read a post

When the server is running, send a JSON request to http://localhost:8080/posts. In PowerShell, run:

curl.exe -i -X POST http://localhost:8080/posts `
  -H "Content-Type: application/json" `
  --data-raw '{"title":"Quarkus cookbook","content":"My first post"}'

The response has status 201 and a Location header. To list posts, run:

curl.exe http://localhost:8080/posts

Verify the sample

Stop development mode, then run the module's tests:

./mvnw test

On Windows, run mvnw.cmd test. The module includes PostRepositoryTest.

What's next