«Браузер Spring REST и HAL» - Spring на русском

«1. Обзор

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

Затем мы воспользуемся Spring для создания простого REST API с несколькими интересными конечными точками и заполним нашу базу данных тестовыми данными.

Наконец, используя браузер HAL, мы изучим наш REST API и узнаем, как перемещаться по содержащимся в нем данным.

2. HAL и браузер HAL

Язык гипертекстовых приложений JSON, или HAL, представляет собой простой формат, обеспечивающий согласованный и простой способ создания гиперссылок между ресурсами в нашем API. Включение HAL в наш REST API делает его гораздо более доступным для пользователей, а также делает его самодокументируемым.

Он работает, возвращая данные в формате JSON, который содержит соответствующую информацию об API.

Модель HAL вращается вокруг двух простых концепций.

Ресурсы, которые содержат:

Ссылки на соответствующие URI Состояние встроенных ресурсов

Ссылки:

Целевой URI Отношение, или rel, к ссылке Несколько других необязательных свойств, помогающих при амортизации и согласовании содержимого и т. д.

Браузер HAL был создан тем же человеком, который разработал HAL, и предоставляет встроенный в браузер графический интерфейс для работы с REST API.

Теперь мы создадим простой REST API, подключим браузер HAL и изучим его функции.

3. Зависимости

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

Во-первых, зависимость для проектов на основе Maven:

<dependency>
    <groupId>org.springframework.data</groupId>
    <artifactId>spring-data-rest-hal-explorer</artifactId>
    <version>3.4.1.RELEASE</version>
</dependency>

Если вы строите с помощью Gradle, вы можете добавить эту строку в свой файл build.gradle:

compile group: 'org.springframework.data', name: 'spring-data-rest-hal-explorer', version: '3.4.1.RELEASE'

4. Создание простого REST API

4.1. Простая модель данных

В нашем примере мы настроим простой REST API для просмотра различных книг в нашей библиотеке.

Здесь мы определяем простую сущность книги, содержащую соответствующие аннотации, чтобы мы могли сохранять данные с помощью Hibernate:

@Entity
public class Book {

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

  @NotNull
  @Column(columnDefinition = "VARCHAR", length = 100)
  private String title;

  @NotNull
  @Column(columnDefinition = "VARCHAR", length = 100)
  private String author;

  @Column(columnDefinition = "VARCHAR", length = 1000)
  private String blurb;

  private int pages;

  // usual getters, setters and constructors

}

4.2. Представляем репозиторий CRUD

Далее нам понадобятся конечные точки. Для этого мы можем использовать PagingAndSortingRepository и указать, что мы хотим получать данные из нашей сущности Book.

Этот класс предоставляет простые команды CRUD, а также возможности разбиения на страницы и сортировки прямо из коробки:

@Repository
public interface BookRepository extends PagingAndSortingRepository<Book, Long> {

    @RestResource(rel = "title-contains", path="title-contains")
    Page<Book> findByTitleContaining(@Param("query") String query, Pageable page);

    @RestResource(rel = "author-contains", path="author-contains", exported = false)
    Page<Book> findByAuthorContaining(@Param("query") String query, Pageable page);
}

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

Мы расширили репозиторий, добавив две новые конечные точки:

findByTitleContaining — возвращает книги, содержащие запрос, включенный в заголовок. findByAuthorContaining — возвращает книги из базы данных, в которой автор книги содержит запрос.

Обратите внимание, что наша вторая конечная точка содержит атрибут export = false. Этот атрибут останавливает создание ссылок HAL для этой конечной точки и не будет доступен через браузер HAL.

Наконец, мы загрузим наши данные при запуске Spring, определив класс, реализующий интерфейс ApplicationRunner. Вы можете найти код на GitHub.

5. Установка браузера HAL

Установка браузера HAL чрезвычайно проста при создании REST API с помощью Spring. Пока у нас есть зависимость, Spring автоматически настроит браузер и сделает его доступным через конечную точку по умолчанию.

Все, что нам нужно сделать сейчас, это нажать кнопку запуска и переключиться в браузер. После этого браузер HAL будет доступен по адресу http://localhost:8080/

6. Изучение нашего REST API с помощью браузера HAL

Браузер HAL разбит на две части — проводник и инспектор. Мы разберем и изучим каждый раздел отдельно.

6.1. Проводник HAL

Как это ни звучит, проводник посвящен изучению новых частей нашего API относительно текущей конечной точки. Он содержит панель поиска, а также текстовые поля для отображения настраиваемых заголовков запросов и свойств текущей конечной точки.

Под ними находится раздел ссылок и интерактивный список встроенных ресурсов.

6.2. Использование ссылок

Если мы перейдем к нашей конечной точке /books, мы сможем просмотреть существующие ссылки:

«Эти ссылки генерируются из HAL в соседнем разделе:

"_links": {
    "first": {
      "href": "http://localhost:8080/books?page=0&size=20"
    },
    "self": {
      "href": "http://localhost:8080/books{?page,size,sort}",
      "templated": true
    },
    "next": {
      "href": "http://localhost:8080/books?page=1&size=20"
    },
    "last": {
      "href": "http://localhost:8080/books?page=4&size=20"
    },
    "profile": {
      "href": "http://localhost:8080/profile/books"
    },
    "search": {
      "href": "http://localhost:8080/books/search"
    }
  },

Если мы перейдем к конечной точке поиска, мы также сможем просмотреть пользовательские конечные точки, которые мы создали с помощью PagingAndSortingRepository:

{
  "_links": {
    "title-contains": {
      "href": "http://localhost:8080/books/search/title-contains{?query,page,size,sort}",
      "templated": true
    },
    "self": {
      "href": "http://localhost:8080/books/search"
    }
  }
}

HAL выше показывает нашу title-содержит конечную точку, отображающую подходящие критерии поиска. Обратите внимание, что конечная точка author-contains отсутствует, поскольку мы определили, что ее нельзя экспортировать.

6.3. Просмотр встроенных ресурсов

Встроенные ресурсы показывают сведения об отдельных записях книг на нашей конечной точке /books. Каждый ресурс также содержит свой собственный раздел «Свойства и ссылки»:

6.4. Использование форм

Кнопка со знаком вопроса в столбце GET в разделе ссылок означает, что модальное окно формы можно использовать для ввода пользовательских критериев поиска.

Вот форма для нашей конечной точки title-contains:

The HAL browser selection form

Наш пользовательский URI возвращает первую страницу из 20 книг, заголовок которых содержит слово «Java».

6.5. Инспектор Hal

Инспектор составляет правую часть браузера и содержит заголовки ответа и тело ответа. Эти данные HAL используются для рендеринга ссылок и встроенных ресурсов, которые мы видели ранее в этом руководстве.

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

В этой статье мы вкратце рассказали, что такое HAL, почему он полезен и почему он может помочь нам создавать превосходные самодокументирующиеся API REST.

Мы создали простой REST API с помощью Spring, который реализует PagingAndSortingRepository, а также определяет наши собственные конечные точки. Мы также видели, как исключить определенные конечные точки из браузера HAL.

После определения нашего API мы заполнили его тестовыми данными и подробно изучили с помощью браузера HAL. Мы увидели, как устроен браузер HAL, и элементы управления пользовательского интерфейса, которые позволили нам пройти через API и изучить его данные.

Как всегда, код доступен на GitHub.

«Браузер Spring REST и HAL»