Браузер Spring REST и HAL

1. Обзор

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

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

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

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

JSON Hypertext Application Language , или 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 показывает нашу конечную точку , содержащую заголовок, отображающую подходящие критерии поиска. Обратите внимание, что конечная точка author-contains отсутствует, поскольку мы определили, что ее нельзя экспортировать.

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

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

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

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

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

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

6.5. Хэл Инспектор

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

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

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

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

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

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