Рубрики
Без рубрики

Весенний ОТДЫХ и ХЭЛ Браузер

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

Автор оригинала: baeldung.

1. Обзор

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

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

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

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

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

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

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

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

  • Ссылки на соответствующие URL-адреса
  • Встроенные ресурсы
  • Государство

Связи:

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

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

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

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

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

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


    org.springframework.data
    spring-data-rest-hal-explorer
    3.4.1.RELEASE

Если вы строите с помощью 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 для просмотра различных книг в нашей библиотеке.

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

@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 | и указать, что мы хотим получить данные из нашей Книги сущности.

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

@Repository
public interface BookRepository extends PagingAndSortingRepository {

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

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

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

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

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

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

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

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

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

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

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

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

6.1. Исследователь HAL

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

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

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

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

Читайте ещё по теме: