Skip to content
Tutorials Center
My learning

Topics

Lesson 3 of 36 ยท Getting Started

Your First Endpoint and Live Coding

Write your first Quarkus REST endpoint, run it in dev mode, change code without restarting, use the Dev UI and write the first test for the greeting.

It is time to write code. In this lesson you will create a REST endpoint, run it in dev mode, change it while the application is running and see the result without restarting anything. You will also meet the Dev UI and a first test.

The real commands and annotations are shown as read-only code. The runnable examples are stand-ins: a tiny request router that mimics how @Path and @GET map requests to methods, and a model of live reload that only recompiles when something changed.

The endpoint

Create src/main/java/org/acme/GreetingResource.java:

Java
package org.acme;

import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.PathParam;
import jakarta.ws.rs.Produces;
import jakarta.ws.rs.core.MediaType;

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

    @GET
    @Produces(MediaType.TEXT_PLAIN)
    public String hello() {
        return "Hello from Quarkus";
    }

    @GET
    @Path("/{name}")
    @Produces(MediaType.TEXT_PLAIN)
    public String greet(@PathParam("name") String name) {
        return "Hello, " + name + "!";
    }
}

Read it as a table:

Annotation Meaning
@Path("/hello") on the class Every method lives under /hello
@GET The method answers HTTP GET
@Produces(TEXT_PLAIN) The response has content type text/plain
@Path("/{name}") on a method A sub-path with a variable part
@PathParam("name") Passes that variable into the parameter

You will study each of these in the REST Endpoints chapter. Note that the class has no constructor, no registration and no web.xml. Quarkus finds it during the build because of @Path.

Run it in dev mode

Terminal
./mvnw quarkus:dev

You will see the Quarkus banner and a line like Listening on: http://localhost:8080. Then, in a second terminal or the browser:

Terminal
curl http://localhost:8080/hello
# Hello from Quarkus
curl http://localhost:8080/hello/Maya
# Hello, Maya!

Dev mode runs the application with a file watcher and a test runner. The terminal accepts single-key commands. Press h for help. The most useful ones are:

Key Action
r Resume or pause continuous testing
w Open the application in the browser
d Open the Dev UI
s Force a restart
q Quit

Live coding

Keep dev mode running and change the return line:

Java
return "Hello from Quarkus, edited live";

Save the file and call the URL again. The response is new. You never stopped or rebuilt anything. How does it work? Quarkus notices on the next request that sources changed, recompiles only what is needed and restarts the application in-process. Because Quarkus starts in a fraction of a second, this feels instant.

If you make a mistake, the error is shown in the browser as an error page with the compile message and the offending line. Fix it, save, refresh.

The dev loop

Edit Change a Java file or a property.
Request Call the endpoint or refresh the page.
Recompile Quarkus rebuilds only what changed.
See it The new behaviour answers at once.

No manual restart. Compile errors show in the browser.

1 / 2

A request router stand-in

Below, a small router maps a method and path (with parts) to a handler, just like @Path and @GET. It is plain Java, not Quarkus, but it shows what the framework does for you: match the URL, extract path variables, call your method and write the result.

Java Stand-in: how @Path and @PathParam match requests

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

The last two calls return 404 because no route matches. Real Quarkus answers a known path with the wrong method with 405 Method Not Allowed; this stand-in simplifies that.

The Dev UI

While dev mode runs, open http://localhost:8080/q/dev-ui. This is a web console that lists the installed extensions with their settings. You can browse CDI beans, see configuration values, view endpoints, run tests and (with some extensions) inspect a database. Every extension may contribute a card. The /q/ prefix is reserved for Quarkus tooling, so keep your own paths out of it.

Related built-in endpoints include /q/swagger-ui and /q/openapi (with the OpenAPI extension) and /q/health (with the health extension). You will add them in later lessons.

Your first test

The generated project contains a test. This is the real code:

Java
package org.acme;

import io.quarkus.test.junit.QuarkusTest;
import org.junit.jupiter.api.Test;

import static io.restassured.RestAssured.given;
import static org.hamcrest.CoreMatchers.is;

@QuarkusTest
public class GreetingResourceTest {

    @Test
    public void testHelloEndpoint() {
        given()
          .when().get("/hello")
          .then()
             .statusCode(200)
             .body(is("Hello from Quarkus"));
    }

    @Test
    public void testGreetEndpoint() {
        given()
          .when().get("/hello/Maya")
          .then()
             .statusCode(200)
             .body(is("Hello, Maya!"));
    }
}

@QuarkusTest boots the real application once and tests it over HTTP using REST Assured. In dev mode press r and the tests rerun automatically every time you change code. Testing has its own chapter later in the Quarkus track.

Live reload, modelled

The stand-in below keeps a "compiled" version of a source string and only recompiles when the source text changed. It counts how many compiles happen across several requests, showing why live coding is cheap: unchanged code costs nothing.

Java Stand-in: recompile only when the source changed

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Dev mode is for development only. Never deploy with quarkus:dev: it exposes the Dev UI and trades safety for speed. Production uses the packaged application.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which annotation makes a method answer HTTP GET requests?

    jakarta.ws.rs.GET marks a resource method for GET. Combined with @Path it maps a URL to the method.
  2. 2. When does Quarkus pick up a source change in dev mode?

    Quarkus checks for changes when work arrives and reloads quickly, so you do not restart manually.
  3. 3. Where is the Dev UI served?

    Quarkus tooling lives under the /q/ prefix, and the Dev UI is at /q/dev-ui in dev mode.
  4. 4. What does @QuarkusTest do?

    It boots the application once for the test class so tests can use real endpoints, injection and configuration.

Summary

  • @Path, @GET and @Produces turn a class into a REST resource with no further registration.
  • @PathParam binds URL variables to method parameters.
  • ./mvnw quarkus:dev gives live reload, continuous testing and the Dev UI at /q/dev-ui.
  • @QuarkusTest with REST Assured tests the real application over HTTP.
  • Dev mode is never a production mode.

Next: Extensions and the BOM