Rest java что это
Spring REST с примером
Сегодня поговорим о такой теме как REST API. Попробуем понять что же это такое и напишем свой REST с помощью Spring Boot.
Данная статья является прямым продолжением Spring Boot — пример с Postgres и JPA. Поэтому объяснять что такое Spring Boot я уже не буду. Проект, к которому я буду подключать REST, я также взял из статьи указаной выше.
Для начала, предлагаю разбить статью на план:
Rest (representational state transfer) — это программный архитектурный стиль для создания веб сервисов. Веб сервисы, которые соответствуют Rest стилю называют RESTful.
Данные системы предназначены для передачи и манипулирования данными по сети с помощью предварительного написанного набора операций.
ФУХ… Написанное выше — это перевод из Википедии;) Такое нелегко запомнить, а тем более понять. Если рассказывать о данном стиле более просто то: Rest это очень удобная и простая штука для передачи данных. Я намерено упускал из объяснения слово «протокол». Потому что REST это НЕ ПРОТОКОЛ. И это одно из его главных отличий от SOAP.
Вот мы и подошли к разнице между REST и SOAP.
Почему я так хочу затронуть этот момент в данной статье? Данный вопрос очень часто задают на собеседованиях. В том числе и я;) И, к сожалению, многие кандидаты не могут ответить достаточно быстро и просто на такой, казалось бы, банальный вопрос.
Вот Вам пару отличий данных подходов:
Если Вы скажете хотя бы первое отличие — это уже будет 90% ответа. Именно то, что REST не протокол, зачастую забывают или не знают большинство кандидатов.
Теперь, перейдем на практичный пример реализации REST API с помощью Spring Boot.
Сейчас Вы увидите — насколько просто и быстро сделать данное API на Spring Boot. Фреймворк делает всю черновую работу за программиста и оставляет возможность просто сосредоточить усилия на бизнес-проблеме.
Для начала нам нужен простой проект Spring Boot. Я выкачал его из репозитория из предыдущей статьи. По желанию, можно создать проект с нуля. Как это делать можете также почитать из других моих статей по Spring. Например, в моей недавней статье Spring scheduler — выполнение кода по расписанию.
Главное, что нужно добавить для возможности реализации REST это зависимости для веб.
Все! Наш проект готов к написанию REST API. Мой проект выглядит так:
Если Вы все делали по инструкции — то проект должен быть примерно похож. За исключением класса UsersController. Его у Вас пока нет. Давайте его напишем.
Для начала создадим пакет controller. В него поместим класс UsersController.
Для того, чтобы данный класс стал рест контроллером достаточно навесить на него аннотацию @RestController. Spring теперь будет обслуживать данный класс как REST API.
А дальше все по сценарию контроллеров которые мы уже видели в статье Spring MVC первое веб приложение. Только вместо того, чтобы возвращать страницы, мы будем возвращать JSON объекты.
Как я уже упоминал ранее, REST позволяет работать с любым типом данных и Spring Boot нас в этом никак не ограничивает. Просто, по умолчанию, если ничего не указать в методе — то будет возвращать JSON. Spring использует библиотеку Jackson для того чтобы конвертировать объекты Java в JSON и наоборот. Подключать ее дополнительно не нужно.
Для того, чтобы возвращать xml необходимо добавить библиотеку jackson-dataformat-xml. Вот ее полный код:
Теперь, посмотрим на сам код контроллера:
Попытаюсь просто объяснить что происходит в данном примере.
В главном классе Spring Boot я добавил небольшой метод для заполнения базы данных после запуска приложения. Для тех, кому лень скачать проект с гитхаба, дублирую этот класс здесь:
После запуска приложения наша база данных заполниться этими полями. Теперь, можно взять Postman или просто попробовать вызвать наши методы через браузер.
вызов рест ендпоинта в браузере
В постман результат будет иметь более привлекательный вид:
И чтобы создать нового пользователя нужно вызвать метод POST с телом нового пользователя:
Результатом будет создание нового пользователя в базе данных.
Как видите, код очень простой и требует минимальных настроек со стороны программиста. Новые фреймворки и инструменты позволяют сосредоточить усилия на проблеме, вместо настроек проекта и кода. Что, конечно же, не может не радовать.
Это все, что касается REST на Spring Boot. Дальнейшие нюансы Вы уже увидите когда сами начнете эксперементировать с кодом.
Введение в REST API — RESTful веб-сервисы
Эта статья начинает серию постов о разработке REST API:
Intro to RESTful Web Services
REST означает REpresentational State Transfer (Википедия: «передача состояния представления»). Это популярный архитектурный подход для создания API в современном мире.
Вы изучите:
Что такое REST?
REST расшифровывается как REpresentational State Transfer. Это был термин, первоначально введен Роем Филдингом (Roy Fielding), который также был одним из создателей протокола HTTP. Отличительной особенностью сервисов REST является то, что они позволяют наилучшим образом использовать протокол HTTP. Теперь давайте кратко рассмотрим HTTP.
Краткий обзор HTTP
Давайте сначала откроем браузер и зайдем на веб-страницу:
А затем щелкните на одной из страниц результатов:
Далее мы можем нажать на ссылку на странице, на которой мы оказались:
И перейти на другую страницу:
Вот как мы обычно просматриваем веб страницы.
Когда мы просматриваем страницы в Интернете, за кулисами происходит много вещей. Ниже приведено упрощенное представление о том, что происходит между браузером и серверами, работающими на посещаемых веб-сайтах:
Протокол HTTP
Когда вы вводите в браузере URL-адрес, например www.google.com, на сервер отправляется запрос на веб-сайт, идентифицированный URL-адресом.
Затем этот сервер формирует и выдает ответ. Важным является формат этих запросов и ответов. Эти форматы определяются протоколом HTTP — Hyper Text Transfer Protocol.
Когда вы набираете URL в браузере, он отправляет запрос GET на указанный сервер. Затем сервер отвечает HTTP-ответом, который содержит данные в формате HTML — Hyper Text Markup Language. Затем браузер получает этот HTML-код и отображает его на экране.
Допустим, вы заполняете форму, присутствующую на веб-странице, со списком элементов. В таком случае, когда вы нажимаете кнопку «Submit» (Отправить), HTTP-запрос POST отправляется на сервер.
HTTP и RESTful веб-сервисы
HTTP обеспечивает базовый уровень для создания веб-сервисов. Поэтому важно понимать HTTP. Вот несколько ключевых абстракций.
Ресурс
Ресурс — это ключевая абстракция, на которой концентрируется протокол HTTP. Ресурс — это все, что вы хотите показать внешнему миру через ваше приложение. Например, если мы пишем приложение для управления задачами, экземпляры ресурсов будут следующие:
URI ресурса
Когда вы разрабатываете RESTful сервисы, вы должны сосредоточить свое внимание на ресурсах приложения. Способ, которым мы идентифицируем ресурс для предоставления, состоит в том, чтобы назначить ему URI — универсальный идентификатор ресурса. Например:
REST и Ресурсы
Важно отметить, что с REST вам нужно думать о приложении с точки зрения ресурсов:
Определите, какие ресурсы вы хотите открыть для внешнего мира
Используйте глаголы, уже определенные протоколом HTTP, для выполнения операций с этими ресурсами.
Вот как обычно реализуется служба REST:
Компоненты HTTP
HTTP определяет следующую структуру запроса:
Методы HTTP-запроса
Метод, используемый в HTTP-запросе, указывает, какое действие вы хотите выполнить с этим запросом. Важные примеры:
Код статуса ответа HTTP
Код состояния всегда присутствует в ответе HTTP. Типичные примеры:
Резюме
В статье приведен на верхнем уровне обзор архитектурного стиля REST. Подчеркивается тот факт, что HTTP является основным строительным блоком REST сервисов. HTTP — это протокол, который используется для определения структуры запросов и ответов браузера. Мы видели, что HTTP имеет дело главным образом с ресурсами, доступными на веб-серверах. Ресурсы идентифицируются с помощью URI, а операции над этими ресурсами выполняются с использованием глаголов, определенных протоколом HTTP.
Наконец, мы рассмотрели, как службы REST наилучшим образом используют функции, предлагаемые HTTP, для предоставления ресурсов внешнему миру. REST не накладывает никаких ограничений на форматы представления ресурсов или на определение сервиса.
Java Blog
Что такое REST?
Принципы REST
HTTP методы
Используйте HTTP методы для сопоставления операций CRUD (создание, получение, обновление, удаление) с HTTP запросами.
Получить информацию. GET-запросы должны быть безопасными и идемпотентными, то есть независимо от того, сколько раз они повторяются с одинаковыми параметрами, результаты одинаковы. Они могут иметь побочные эффекты, но пользователь не ожидает их, поэтому они не могут быть критическими для работы системы. Запросы также могут быть частичными или условными.
Получить адрес с идентификатором 1:
Запрос, чтобы ресурс в URI что-то сделал с предоставленным объектом. Часто POST используется для создания новой сущности, но также может использоваться для обновления сущности.
Создать новый адрес:
Изменить адрес с идентификатором 1:
Примечание. PUT заменяет существующую сущность. Если предоставляется только подмножество элементов данных, остальные будут заменены пустыми или null.
PATCH
Обновить только указанные поля объекта в URI. Запрос PATCH не является ни безопасным, ни идемпотентным (RFC 5789). Это связано с тем, что операция PATCH не может гарантировать, что весь ресурс обновлен.
DELETE
Запросить удаление ресурса; тем не менее, ресурс не должен быть удален немедленно. Это может быть асинхронный или длительный запрос.
Удалить адрес с идентификатором 1:
HTTP коды состояния
Коды состояния указывают результат HTTP-запроса.
REST API на Java без фреймворков
Перевод статьи подготовлен специально для студентов курса «Разработчик Java».
В экосистеме Java есть много фреймворков и библиотек. Хотя и не так много, как в JavaScript, но они и не устаревают так быстро. Тем не менее, это заставило меня задуматься о том, что мы уже забыли, как писать приложения без фреймворков.
Вы можете сказать, что Spring — это стандарт и зачем изобретать велосипед? А Spark — это хороший удобный REST-фреймворк. Или Light-rest-4jis. И я скажу, что вы, конечно, правы.
Но вместе с фреймворком, помимо готовой функциональности, вы получаете много магии, сложности с изучением, дополнительные функции, которые вы, скорее всего, не будете использовать, а также баги. И чем больше стороннего кода в вашем сервисе, тем больше вероятность того, что у вас будут ошибки.
Сообщество open source очень активное, и есть большая вероятность, что ошибки в фреймворке будут быстро исправлены. Но все же, я хотел бы призвать вас подумать, действительно ли вам нужен фреймворк. Если у вас небольшой сервис или консольное приложение, возможно, вы сможете обойтись без него.
Что вы можете получить (или потерять), используя чистый Java-код? Подумайте об этом:
Когда я начал писать этот код, то часто сталкивался с ситуациями, когда отсутствовал функционал, который есть в Spring из коробки. В эти моменты, вместо того, чтобы взять Spring, надо было переосмыслить и разработать все самостоятельно.
Я понял, что для решения реальных бизнес-задач я, все же, предпочел бы использовать Spring, а не изобретать велосипед. Тем не менее, я считаю, что это упражнение было довольно интересным опытом.
Начинаем
Я буду описывать каждый шаг, но не всегда буду приводить полный исходный код. Полный код вы можете посмотреть в отдельных ветках git-репозитория.
и Jackson для JSON-сериализации
Для упрощения POJO-классов будем использовать Lombok:
и vavr для средств функционального программирования
Исходный код в ветке step-1.
Первый эндпоинт
Веб-сервер запускается на порту 8000 и предоставляет эндпоинт, который просто возвращает Hello. Это можно проверить, например, используя curl:
Исходный код в ветке step-2.
Поддержка разных HTTP-методов
Наш первый эндпоинт работает отлично, но вы можете заметить, что независимо от того, какой HTTP-метод использовать, он всегда отвечает одинаково.
Первое, что нужно сделать, это добавить код для различения методов, например:
Попробуйте еще раз такой запрос:
ответ будет примерно таким:
Исходный код в ветке step-3.
Парсинг параметров запроса
Парсинг параметров запроса — это еще одна «функция», которую нам нужно реализовать самостоятельно.
Мы могли бы распарсить параметры следующим образом:
и использовать, как показано ниже:
Полный пример в ветке step-4.
Аналогично, если мы хотим использовать параметры в path. Например:
Чтобы получить элемент по нам нужно распарсить url самостоятельно. Это становится громоздким.
Безопасность
Часто нам нужно защитить доступ к некоторым эндпоинтам. Например, это можно сделать, используя базовую аутентификацию (basic authentication).
Для каждого HttpContext мы можем установить аутентификатор, как показано ниже:
Значение “myrealm” в конструкторе BasicAuthenticator — это имя realm. Realm — это виртуальное имя, которое может быть использовано для разделения областей аутентификации.
Подробнее об этом можно прочитать в RFC 1945.
Теперь вы можете вызвать этот защищенный эндпоинт, добавив заголовок Authorization :
Для аутентификации в реальном приложении вы, вероятно, получите учетные данные из заголовка и сравните их с именем пользователя и паролем, хранящимися в базе данных.
Если вы не укажете заголовок, то API ответит статусом
Полный пример в ветке step-5.
JSON, обработка исключений и прочее
Теперь пришло время для более сложного примера.
Из моего опыта в разработке программного обеспечения наиболее распространенным API, который я разрабатывал, был обмен JSON.
Мы собираемся разработать API для регистрации новых пользователей. Для их хранения будем использовать базу данных в памяти.
У нас будет простой доменный объект User :
Я использую Lombok, чтобы избавится от бойлерплейта (конструкторы, геттеры).
В REST API я хочу передать только логин и пароль, поэтому я создал отдельный объект:
Объекты User создаются в сервисе, который будем использовать в обработчике API. Сервисный метод просто сохраняет пользователя.
В реальном приложении можно сделать больше. Например, отправлять события после успешной регистрации пользователя.
Реализация репозитория выглядит следующим образом:
Наконец, склеим все вместе в handle() :
Здесь JSON-запрос преобразуется в объект RegistrationRequest :
Также мне нужно преобразовать объект RegistrationResponse обратно в JSON-строку. Для этого используем Jackson
( com.fasterxml.jackson.databind.ObjectMapper ).
Вот как я создаю новый обработчик ( handler ) в main() :
Рабочий пример можно найти в ветке step-6. Там я также добавил глобальный обработчик исключений для отправки стандартных JSON-сообщений об ошибках. Например, если HTTP-метод не поддерживается или запрос к API сформирован неправильно.
Вы можете запустить приложение и попробовать один из следующих запросов:
REST-сервис на Java — это просто
Многим программистам Java-технологии могут показаться монструозными и сложными для понимания. В этой небольшой статье я бы хотел показать, что при желании можно собрать приложение из довольно простых компонентов, не прибегая к мега-фреймворкам.
В качестве примера я выбрал простенький REST-сервис. Для описания ресурсов будет использоваться Jersey. Как бонус, будет показано использование Dependency Injection фреймворка Google Guice. Можно было бы и без него, но я не хочу, что бы пример показался слишком игрушечным и оторванным от жизни. Весь пример я постараюсь уложить в примерно 50 строк в одном файле и не будет использовано ни строчки XML.
1. Опишем простенький класс, который будет предоставлять доступ к некоторой информации. Пусть это будет счетчик вызовов:
@Singleton
public static class Counter <
private final AtomicInteger counter = new AtomicInteger(0);
public int getNext() <
return counter.incrementAndGet();
>
>
Аннотация Singleton нужна для указания джуйсу, что объект должен быть синглтоном 🙂
2. Опишем сервис, который будет возращать нам что-то, попутно дергая counter:
@Path( «/hello» )
public static class Resource <
@Inject Counter counter;
@GET
public String get () <
return «Hello, User number » + counter.getNext();
>
>
3. Теперь подружим Jersey и Guice. Я воспользовался готовой интеграцией, она называется jersey-guice. Интеграция осуществляется через сервлет/фильтр GuiceContainer, для использования которого нужно объявить ServletModule из расширения guice-servlet-module и указать, что нужные нам запросы будут обрабатываться GuiceContainer, что позволит объявлять Jersey ресурсы в контексте Guice.
public static class Config extends GuiceServletContextListener <
@Override
protected Injector getInjector() <
return Guice.createInjector( new ServletModule() <
@Override
protected void configureServlets() <
bind(Resource. class );
bind(Counter. class );
serve( «*» ).with(GuiceContainer. class );
>
>);
>
>
Там же мы забайндили Counter и Resource.
4. Осталось запустить все это добро, используя сервлет-контейнер. Для этого нам совершенно не обязательно собирать war-ку и деплоить в какой-нибудь Tomcat. Можно воспользоваться встраиваемым контейнером. На ум приходят Jetty и Grizzly. Я выбрал последний. Вот код, который запускает сервер:
Обратите внимание, что пришлось объявить пустой сервлет:
@SuppressWarnings( «serial» )
public static class DummySevlet extends HttpServlet
Он нужен, что бы Guice-фильтр сработал. Если не будет ни одного сервлета, Grizzly не будет передавать запрос никаким фильтрам.
Вот пожалуй и все. Далее приведу весь код:
@Path( «/hello» )
public static class Resource <
@Inject Counter counter;
@GET
public String get () <
return «Hello, User number » + counter.getNext();
>
>
@Singleton
public static class Counter <
private final AtomicInteger counter = new AtomicInteger(0);
public int getNext() <
return counter.incrementAndGet();
>
>
public static class Config extends GuiceServletContextListener <
@Override
protected Injector getInjector() <
return Guice.createInjector( new ServletModule() <
@Override
protected void configureServlets() <
bind(Resource. class );
bind(Counter. class );
serve( «*» ).with(GuiceContainer. class );
>
>);
>
>
@SuppressWarnings( «serial» )
public static class DummySevlet extends HttpServlet