REST-эндпоинты

REST-эндпоинт — это адрес, на который клиент отправляет HTTP-запрос, и код, который на него отвечает. В Quarkus эндпоинты пишут в классах-ресурсах с аннотациями стандарта Jakarta REST. Реализацию стандарта даёт расширение Quarkus REST (quarkus-rest), оно уже подключено в проекте вместе с rest-jackson.

Первый ресурс блога

Удалите сгенерированные GreetingResource.java и оба теста GreetingResourceTest.java, GreetingResourceIT.java — они больше не нужны. Создайте файл ресурса для постов:

// src/main/java/com/example/blog/PostResource.java
package com.example.blog;
 
import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.Produces;
import jakarta.ws.rs.core.MediaType;
 
@Path("/posts")
public class PostResource {
 
    @GET
    @Produces(MediaType.TEXT_PLAIN)
    public String list() {
        return "Здесь будет список постов";
    }
}

@Path("/posts") задаёт адрес, @GET — HTTP-метод, @Produces — тип ответа. Если dev mode запущен, класс заработает сразу после сохранения:

curl http://localhost:8080/posts

Терминал напечатает Здесь будет список постов.

Путь из двух частей

@Path можно поставить и на метод. Тогда адрес складывается из пути класса и пути метода:

// src/main/java/com/example/blog/PostResource.java
@GET
@Path("/latest")
@Produces(MediaType.TEXT_PLAIN)
public String latest() {
    return "Последний пост";
}

Этот метод отвечает на GET /posts/latest.

HTTP-методы

Один и тот же путь может обслуживать несколько методов: GET /posts вернёт список, а POST /posts создаст пост.

Тип ответа

@Produces говорит, в каком формате метод отдаёт данные, @Consumes — какой формат он принимает. Часто используемые значения — MediaType.TEXT_PLAIN и MediaType.APPLICATION_JSON. Когда метод возвращает объект, а не строку, Quarkus REST сам выбирает JSON, поэтому в следующих уроках @Produces почти не понадобится.

Один объект на все запросы

В Quarkus REST класс-ресурс по умолчанию создаётся один раз и обслуживает все запросы (область видимости @Singleton). Поэтому в полях ресурса не стоит хранить данные конкретного запроса — для этого есть параметры метода.

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

Если вызвать существующий адрес методом, которого у ресурса нет, Quarkus ответит 405:

curl -i -X PUT http://localhost:8080/posts

HTTP/1.1 405 Method Not Allowed
content-length: 0

Это не ошибка сервера: адрес найден, но обработчика для PUT нет. Проверьте аннотацию метода и флаг -X в curl. Если же адреса нет совсем, ответ будет 404 Not Found.