Spring Boot
2026-02-26 20:23 Diff
https://ru.hexlet.io/courses/java-spring-boot/lessons/rest-api/theory_unit

Spring Boot в основном используется для создания API. В этом уроке вы узнаете, что это такое, зачем нужно и как с этим работать.

По отношению к веб-приложениям, API — это набор маршрутов, созданных для использования другими сервисами или приложениями. API обычно возвращают данные в JSON-формате, чтобы их было удобно читать и обрабатывать.

Например, такой API есть у GitHub. Оно активно используется в редакторах c интеграцией с GitHub API, а также в онлайн-инструментах для создания десктопных приложений и даже консольных утилит:

Способов создавать API много. Самым распространенным и базовым считается REST API. Это архитектурный подход, очень сильно полагающийся на принципы работы самого HTTP. Далее мы будем изучать особенности этого подхода и строить наш код на его основе.

Ориентированность на ресурсы

В REST-подходе маршруты строятся вокруг ресурсов. Действия над ними в основном определяются HTTP-методами. Так выглядят маршруты типичного CRUD:

Здесь ресурс — это пользователь. Обычно во фреймворках берут имя ресурса, ставят его во множественное число и делают частью маршрута. А вот в коде все по-другому: обработчики одного ресурса помещают в общий класс, называемый контроллером. Сам класс располагают в соответствующей директории:

С точки зрения Spring Boot контроллером считается любой класс с аннотацией @RestController. Для пользователя он будет выглядеть так:

Это не означает, что все обработчики, связанные с каким-то ресурсом, находятся ровно в одном контроллере. У ресурсов бывают разные представления, которые требуют других обработчиков для одних и тех же действий. Представьте себе ссылку /companies/google/users для маршрута /companies/{id}/users. Такой маршрут может выводить сотрудников конкретной компании, у которых есть собственное представление и собственные действия. Здесь для работы с этими пользователями в коде будет свой контроллер:

Дополнительные действия

CRUD — это базовый набор операций, но в реальных проектах встречаются запуски процессов, переводы сущностей в новые состояния и другие дополнительные действия. Предположим, что мы хотим опубликовать статью на сайте. Чтобы это сделать, нужен дополнительный обработчик со своим маршрутом:

Префикс /api

Этот пункт не относится напрямую к понятию REST, но считается общепринятой практикой. Если маршрут считается частью API, то его располагают под префиксом /api. Например, маршрут /users превращается в /api/users. То же самое происходит со всеми остальными маршрутами. Иногда этого недостаточно и вводится версионирование: /api/v1/users.

В рамках курса мы остановимся на варианте /api/users. Чтобы добиться такого результата, можно добавить этот префикс в каждый маршрут, но получится дублирование. Упростить эту задачу можно с помощью аннотации @RequestMapping, которой можно пометить контроллер:

Если контроллеров больше одного, то придется задавать эту аннотацию в каждом контроллере.

Spring Boot дает возможность указать префикс на уровне всего приложения, но так лучше не делать, потому что пропадет возможность создавать что-то вне /api, и перестанет работать главная страница.

Коды ответа

Другой важный элемент в REST API — это коды ответа. В этой части REST API полностью полагается на правильное использование стандарта HTTP. Например, для созданного ресурса правильный код ответа — это 201, а не 200. Если произошла внутренняя ошибка — это 500, а если ошибка валидации — это 422. Подробнее об ошибках можно прочитать здесь.

В Spring Boot коды возврата можно задавать несколькими способами. Иногда это происходит через ResponseEntity, но в большинстве ситуаций для этого достаточно аннотации @ResponseStatus: