«1. Обзор

В этой статье объясняются основы Spring Data REST и показано, как использовать его для создания простого REST API.

В общем, Spring Data REST построен на основе проекта Spring Data и позволяет легко создавать веб-сервисы REST на основе гипермедиа, которые подключаются к репозиториям Spring Data — все с использованием HAL в качестве управляющего типа гипермедиа.

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

2. Зависимости Maven

Для нашего простого приложения требуются следующие зависимости Maven: 

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter</artifactId>
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId
    <artifactId>spring-boot-starter-data-rest</artifactId></dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-data-jpa</artifactId>
</dependency>
<dependency>
    <groupId>com.h2database</groupId>
    <artifactId>h2</artifactId>
</dependency>

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

3. Написание приложения

Мы начнем с написания объекта домена, представляющего пользователя нашего веб-сайта: 

@Entity
public class WebsiteUser {

    @Id
    @GeneratedValue(strategy = GenerationType.AUTO)
    private long id;

    private String name;
    private String email;

    // standard getters and setters
}

У каждого пользователя есть имя и адрес электронной почты, а также автоматически сгенерированный идентификатор. . Теперь мы можем написать простой репозиторий: 

@RepositoryRestResource(collectionResourceRel = "users", path = "users")
public interface UserRepository extends PagingAndSortingRepository<WebsiteUser, Long> {
    List<WebsiteUser> findByName(@Param("name") String name);
}

Это интерфейс, позволяющий выполнять различные операции с объектами WebsiteUser. Мы также определили пользовательский запрос, который предоставит список пользователей на основе заданного имени.

Аннотация @RepositoryRestResource не является обязательной и используется для настройки конечной точки REST. Если бы мы решили его опустить, Spring автоматически создал бы конечную точку в «/websiteUsers» вместо «/users».

Наконец, мы напишем стандартный основной класс Spring Boot для инициализации приложения: 

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

Вот и все! Теперь у нас есть полнофункциональный REST API. Давайте посмотрим на это в действии.

4. Доступ к REST API

Если мы запустим приложение и перейдем по адресу http://localhost:8080/ в браузере, мы получим следующий JSON: 

{
  "_links" : {
    "users" : {
      "href" : "http://localhost:8080/users{?page,size,sort}",
      "templated" : true
    },
    "profile" : {
      "href" : "http://localhost:8080/profile"
    }
  }
}

Как видите, доступна конечная точка «/users», и у нее уже есть параметры «?page», «size» и «sort».

Существует также стандартная конечная точка «/profile», которая предоставляет метаданные приложения. Важно отметить, что ответ структурирован таким образом, что соответствует ограничениям стиля архитектуры REST. В частности, он обеспечивает унифицированный интерфейс и самоописательные сообщения. Это означает, что каждое сообщение содержит достаточно информации, чтобы описать, как обрабатывать сообщение.

В нашем приложении еще нет пользователей, поэтому переход по адресу http://localhost:8080/users покажет пустой список пользователей. Давайте используем curl для добавления пользователя. 

$ curl -i -X POST -H "Content-Type:application/json" -d '{  "name" : "Test", \ 
"email" : "[email protected]" }' http://localhost:8080/users
{
  "name" : "test",
  "email" : "[email protected]",
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/users/1"
    },
    "websiteUser" : {
      "href" : "http://localhost:8080/users/1"
    }
  }
}

Давайте также взглянем на заголовки ответов: 

HTTP/1.1 201 Created
Server: Apache-Coyote/1.1
Location: http://localhost:8080/users/1
Content-Type: application/hal+json;charset=UTF-8
Transfer-Encoding: chunked

Вы заметите, что возвращаемый тип содержимого — «application/hal+json». HAL — это простой формат, обеспечивающий согласованный и простой способ создания гиперссылок между ресурсами в вашем API. Заголовок также автоматически содержит заголовок Location, который является адресом, который мы можем использовать для доступа к вновь созданному пользователю.

Теперь мы можем получить доступ к этому пользователю по адресу http://localhost:8080/users/1 

{
  "name" : "test",
  "email" : "[email protected]",
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/users/1"
    },
    "websiteUser" : {
      "href" : "http://localhost:8080/users/1"
    }
  }
}

Вы также можете использовать curl или любой другой клиент REST для выполнения запросов PUT, PATCH и DELETE. Также важно отметить, что Spring Data REST автоматически следует принципам HATEOAS. HATEOAS — это одно из ограничений стиля архитектуры REST, и это означает, что для поиска пути через API следует использовать гипертекст.

Наконец, давайте попробуем получить доступ к пользовательскому запросу, который мы написали ранее, и найти всех пользователей с именем «test». Это можно сделать, перейдя по адресу http://localhost:8080/users/search/findByName?name=test 

{
  "_embedded" : {
    "users" : [ {
      "name" : "test",
      "email" : "[email protected]",
      "_links" : {
        "self" : {
          "href" : "http://localhost:8080/users/1"
        },
        "websiteUser" : {
          "href" : "http://localhost:8080/users/1"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/users/search/findByName?name=test"
    }
  }
}

5. Заключение

В этом руководстве продемонстрированы основы создания простого REST API с помощью Spring Data REST. . Пример, использованный в этой статье, можно найти в связанном проекте GitHub.