Spring REST с примером

Сегодня поговорим о такой теме как REST API. Попробуем понять что же это такое и напишем свой REST с помощью Spring Boot.

Данная статья является прямым продолжением Spring Boot — пример с Postgres и JPA. Поэтому объяснять что такое Spring Boot я уже не буду. Проект, к которому я буду подключать REST, я также взял из статьи указаной выше.

Для начала, предлагаю разбить статью на план:

что такое REST API;
отличие REST от SOAP;
пример REST API на Spring Boot.

Rest (representational state transfer) — это программный архитектурный стиль для создания веб сервисов. Веб сервисы, которые соответствуют Rest стилю называют RESTful.

Данные системы предназначены для передачи и манипулирования данными по сети с помощью предварительного написанного набора операций.

ФУХ… Написанное выше — это перевод из Википедии;) Такое нелегко запомнить, а тем более понять. Если рассказывать о данном стиле более просто то: Rest это очень удобная и простая штука для передачи данных. Я намерено упускал из объяснения слово «протокол». Потому что REST это НЕ ПРОТОКОЛ. И это одно из его главных отличий от SOAP.

Вот мы и подошли к разнице между REST и SOAP.

Почему я так хочу затронуть этот момент в данной статье? Данный вопрос очень часто задают на собеседованиях. В том числе и я;) И, к сожалению, многие кандидаты не могут ответить достаточно быстро и просто на такой, казалось бы, банальный вопрос.

Вот Вам пару отличий данных подходов:

SOAP — протокол, REST — просто архитектурный стиль.
SOAP использует xml, REST зачастую использует JSON, но может использовать любой другой тип данных для передачи. В том числе и xml.
зачастую используют HTTP протокол для REST. Но так как REST не является протоколом, то к нему и нет строгих правил реализации. Поэтому на REST можно построить хоть и FTP передачу данных.

Если Вы скажете хотя бы первое отличие — это уже будет 90% ответа. Именно то, что REST не протокол, зачастую забывают или не знают большинство кандидатов.

Теперь, перейдем на практичный пример реализации REST API с помощью Spring Boot.

Сейчас Вы увидите — насколько просто и быстро сделать данное API на Spring Boot. Фреймворк делает всю черновую работу за программиста и оставляет возможность просто сосредоточить усилия на бизнес-проблеме.

Для начала нам нужен простой проект Spring Boot. Я выкачал его из репозитория из предыдущей статьи. По желанию, можно создать проект с нуля. Как это делать можете также почитать из других моих статей по Spring. Например, в моей недавней статье Spring scheduler — выполнение кода по расписанию.

Главное, что нужно добавить для возможности реализации REST это зависимости для веб.

<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>

Все! Наш проект готов к написанию REST API. Мой проект выглядит так:

Если Вы все делали по инструкции — то проект должен быть примерно похож. За исключением класса UsersController. Его у Вас пока нет. Давайте его напишем.

Для начала создадим пакет controller. В него поместим класс UsersController.

Для того, чтобы данный класс стал рест контроллером достаточно навесить на него аннотацию @RestController. Spring теперь будет обслуживать данный класс как REST API.

А дальше все по сценарию контроллеров которые мы уже видели в статье Spring MVC первое веб приложение. Только вместо того, чтобы возвращать страницы, мы будем возвращать JSON объекты.

Как я уже упоминал ранее, REST позволяет работать с любым типом данных и Spring Boot нас в этом никак не ограничивает. Просто, по умолчанию, если ничего не указать в методе — то будет возвращать JSON. Spring использует библиотеку Jackson для того чтобы конвертировать объекты Java в JSON и наоборот. Подключать ее дополнительно не нужно.

Для того, чтобы возвращать xml необходимо добавить библиотеку jackson-dataformat-xml. Вот ее полный код:

<dependency>			<groupId>com.fasterxml.jackson.dataformat</groupId>
<artifactId>jackson-dataformat-xml</artifactId>
</dependency>

Теперь, посмотрим на сам код контроллера:

package com.javamaster.springjpapostgres.controller;

import com.javamaster.springjpapostgres.entity.Users;
import com.javamaster.springjpapostgres.service.UserService;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

import java.util.List;

@RestController
@RequestMapping("/api")
public class UsersController {

    @Autowired
    private UserService userService;

    @GetMapping("/users")
    List<Users> getAllUsers() {
        return userService.findAll();
    }

    @PostMapping("/users")
    ResponseEntity<Void> createUser(@RequestBody Users user) {
        userService.createUsers(user);
        return ResponseEntity.ok().build();
    }
}

Попытаюсь просто объяснить что происходит в данном примере.

Добавил аннотации RestController и RequestMapping. Первая для того, чтобы спринг понимал, что это Rest, вторая для того, чтобы весь мой класс имел изначальный урл api. Вторая аннотация в принципе необязательна.
Подключил свой UserService класс для того, чтобы успешно использовать его методах контроллера. Если этот момент не понятен — внимательно читаем о внедрении зависимостей в Spring. Данный сервис, как и база данных здесь только по той причине, что нужно где-то брать данные. Мне просто лень писать все заново, вот я взял готовый проект, где уже есть данные.
Далее, я создаю обычные методы языка java и навешиваю на них аннотации, которые будут указывать тип запроса, а внутри будут указывать на путь к данному методу. Например @GetMapping(«/users») будет доступен методом GET и иметь адрес /users. Так как я пометил класс дополнительным адресом api, то путь к моему методу будет api/users. Полный путь к нему будет: протокол://хост:порт/api/users. Если Вы запускаете приложение у себя на компьютере, и ничего не изменили то адрес будет http://localhost:8080/api/users
Не бойтесь ResponseEntity<Void> и ResponseEntity.ok().build() подобных конструкций. Эти объекты находятся в библиотеке Spring и служат для того, чтобы возвращать ответы в определенных форматах. Вместо них можно было просто вернуть строку или не возвращать ничего. Но, клиенту гораздо информативнее и понятнее будет именно хорошо оформленный ответ. А чтобы программист не утруждал себя написанием этих ответов — Spring дает готовые решения.

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

package com.javamaster.springjpapostgres;

import com.javamaster.springjpapostgres.entity.Address;
import com.javamaster.springjpapostgres.entity.Users;
import com.javamaster.springjpapostgres.service.AddressService;
import com.javamaster.springjpapostgres.service.UserService;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.boot.context.event.ApplicationReadyEvent;
import org.springframework.context.event.EventListener;

@SpringBootApplication
public class SpringjpapostgresApplication {

	@Autowired
	private UserService userService;

	public static void main(String[] args) {
		SpringApplication.run(SpringjpapostgresApplication.class, args);
	}

	@EventListener(ApplicationReadyEvent.class)
	private void testJpaMethods(){
		Address address = new Address();
		address.setCity("Kiev");
		address.setHomeNumber("4");
		address.setStreet("Main Street");
		Address address1 = new Address();
		address1.setCity("Lviv");
		Users users = new Users();
		users.setAddress(address);
		users.setEmail("someEmail@gmail.com");
		users.setName("Smith");
		userService.createUsers(users);
		Users users1 = new Users();
		users1.setName("Jon Dorian");
		users1.setEmail("gmailEmail@gmail.com");
		users1.setAddress(address1);
		userService.createUsers(users1);
	}
}

После запуска приложения наша база данных заполниться этими полями. Теперь, можно взять Postman или просто попробовать вызвать наши методы через браузер.

Результат выполнения:

В постман результат будет иметь более привлекательный вид:

И чтобы создать нового пользователя нужно вызвать метод POST с телом нового пользователя:

Результатом будет создание нового пользователя в базе данных.

Как видите, код очень простой и требует минимальных настроек со стороны программиста. Новые фреймворки и инструменты позволяют сосредоточить усилия на проблеме, вместо настроек проекта и кода. Что, конечно же, не может не радовать.

Это все, что касается REST на Spring Boot. Дальнейшие нюансы Вы уже увидите когда сами начнете эксперементировать с кодом.