Параметры пути и запроса

Клиенту часто нужно передать в запросе данные: номер поста, строку поиска, число записей на странице. Для этого есть два места в адресе. Параметр пути — часть самого адреса: в /posts/5 число 5 — это id поста. Параметр запроса (query-параметр) — пары имя=значение после знака вопроса: /posts?search=quarkus&limit=5.

Параметр пути

В @Path параметр записывают в фигурных скобках, а в метод получают через @PathParam:

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

Имя в @PathParam("id") должно совпадать с именем в {id}. Quarkus сам превращает текст из адреса в long:

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

Ответ: Пост №5.

Параметры запроса

Параметры после ? получают через @QueryParam. Если параметр необязательный, ему можно задать значение по умолчанию через @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 + ", не больше " + limit;
}

Этот метод заменяет прежний list() из прошлого урока. Если параметра нет в адресе, строка получает null, а число — значение из @DefaultValue:

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

Поиск: quarkus, не больше 5
Поиск: null, не больше 10

Адрес с ? и & берите в кавычки: иначе командная оболочка поймёт & как свой символ.

Короткие аннотации Quarkus

Кроме стандартных аннотаций Quarkus REST предлагает свои, без повторения имени: @RestPath и @RestQuery из пакета org.jboss.resteasy.reactive. Имя параметра берётся из имени переменной:

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

Работают оба варианта. В курсе мы используем стандартные @PathParam и @QueryParam: их понимает любой фреймворк на Jakarta REST.

Какие типы можно получать

Частая ошибка

Если значение нельзя превратить в нужный тип, например limit=abc для int, Quarkus отвечает 404, а не 400:

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

HTTP/1.1 404 Not Found
content-length: 0

В логе dev mode при этом видна причина: NumberFormatException: For input string: "abc". Так требует стандарт Jakarta REST для @PathParam и @QueryParam. Если нужен понятный клиенту ответ, принимайте параметр как String и проверяйте его сами или используйте валидацию из урока о проверке данных.