Path and query parameters

A client often needs to pass data in a request: a post number, a search string, the number of records per page. The address has two places for that. A path parameter is part of the address itself: in /posts/5 the number 5 is the post id. A query parameter is a name=value pair after the question mark: /posts?search=quarkus&limit=5.

A path parameter

In @Path the parameter is written in curly braces, and the method receives it through @PathParam:

// src/main/java/com/example/blog/PostResource.java
@GET
@Path("/{id}")
@Produces(MediaType.TEXT_PLAIN)
public String get(@PathParam("id") long id) {
    return "Post #" + id;
}

The name in @PathParam("id") must match the name in {id}. Quarkus turns the text from the address into a long by itself:

curl http://localhost:8080/posts/5

The answer is Post #5.

Query parameters

The values after ? are received through @QueryParam. An optional parameter can get a default value with @DefaultValue:

// src/main/java/com/example/blog/PostResource.java
@GET
@Produces(MediaType.TEXT_PLAIN)
public String list(@QueryParam("search") String search,
                   @QueryParam("limit") @DefaultValue("10") int limit) {
    return "Search: " + search + ", at most " + limit;
}

This method replaces the list() method from the previous lesson. If a parameter is missing from the address, a string gets null and a number gets the value from @DefaultValue:

curl "http://localhost:8080/posts?search=quarkus&limit=5"
curl http://localhost:8080/posts

Search: quarkus, at most 5
Search: null, at most 10

Put an address with ? and & in quotes: otherwise the shell treats & as its own symbol.

Quarkus shortcut annotations

Besides the standard annotations, Quarkus REST offers its own ones that do not repeat the name: @RestPath and @RestQuery from the org.jboss.resteasy.reactive package. The parameter name is taken from the variable name:

// src/main/java/com/example/blog/PostResource.java
@GET
@Path("/{id}")
@Produces(MediaType.TEXT_PLAIN)
public String get(@RestPath long id) {
    return "Post #" + id;
}

Both variants work. In this course we use the standard @PathParam and @QueryParam: any Jakarta REST framework understands them.

Which types you can receive

Common mistake

If a value cannot be turned into the required type, for example limit=abc for an int, Quarkus answers 404, not 400:

curl -i "http://localhost:8080/posts?limit=abc"

HTTP/1.1 404 Not Found
content-length: 0

The dev mode log shows the reason: NumberFormatException: For input string: "abc". This is what the Jakarta REST standard requires for @PathParam and @QueryParam. If you need an answer the client can understand, accept the parameter as a String and check it yourself, or use validation from the lesson on checking data.