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¶
- Change to the
restmodule:
cd rest
- 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¶
- Compare the Spring programming model in Build a Spring API on Quarkus.
- See Hibernate Reactive with Panache for more backend details.