Hal explorer что это
Обновлено: 03.07.2024
Узнайте, как исследовать API-интерфейсы REST с помощью браузера HAL.
1. Обзор
В этом уроке мы обсудим что такое HAL и почему он полезен, прежде чем представить браузер HAL .
Затем мы будем использовать Spring для создания простого REST API с несколькими интересными конечными точками и заполнения нашей базы данных некоторыми тестовыми данными.
Наконец, используя браузер HAL, мы изучим наш REST API и узнаем, как просматривать данные, содержащиеся в нем.
2. HAL и браузер HAL
Он работает, возвращая данные в формате JSON, в котором содержится соответствующая информация об API.
Модель HAL вращается вокруг двух простых концепций.
Ресурсы, которые содержат:
- Ссылки на соответствующие URL-адреса
- Встроенные ресурсы
- Государство
- Целевой URI
- Отношение или отношение к ссылке
- Несколько других дополнительных свойств, которые помогут с амортизацией, согласованием содержимого и т. Д
Браузер HAL был создан тем же человеком, который разработал HAL, и предоставляет графический интерфейс в браузере для просмотра вашего REST API .
Теперь мы создадим простой REST API, подключим браузер HAL и изучим его функции.
3. Зависимости
Ниже приведена единственная зависимость, необходимая для интеграции браузера HAL в наш REST API. Вы можете найти остальные зависимости для API в коде GitHub .
Во-первых, зависимость для проектов на основе Maven:
Если вы строите с помощью Gradle, вы можете добавить эту строку в файл build.gradle :
4. Создание простого REST API
4.1. Простая модель данных
В нашем примере мы настроим простой REST API для просмотра различных книг в нашей библиотеке.
Здесь мы определяем простую сущность книги, которая содержит соответствующие аннотации, чтобы мы могли сохранять данные в режиме гибернации:
4.2. Внедрение репозитория CRUD
Затем нам понадобятся некоторые конечные точки. Для этого мы можем использовать PagingAndSortingRepository | и указать, что мы хотим получить данные из нашей Книги сущности.
Этот класс предоставляет простые команды CRUD, а также возможности подкачки и сортировки прямо из коробки:
Если это выглядит немного странно, или если вы хотите узнать больше о репозиториях Spring, вы можете прочитать больше здесь .
Мы расширили репозиторий, добавив две новые конечные точки:
- findByTitleContaining – возвращает книги, содержащие запрос, включенный в заголовок
- findByAuthorContaining – возвращает книги из базы данных, в которой автор книги содержит запрос
Обратите внимание, что наша вторая конечная точка содержит атрибут export //. Этот атрибут останавливает создание ПОЛУ-ссылок для этой конечной точки и не будет доступен через браузер HAL.
Наконец, мы загрузим наши данные при запуске Spring, определив класс, реализующий интерфейс Application Runner . Вы можете найти код на GitHub .
5. Установка браузера HAL
Настройка браузера HAL удивительно проста при создании REST API с помощью Spring. Пока у нас есть зависимость, Spring автоматически настроит браузер и сделает его доступным через конечную точку по умолчанию.
6. Изучение нашего REST API С помощью браузера HAL
Браузер HAL разбит на две части – проводник и инспектор . Мы разберем и исследуем каждый раздел отдельно.
6.1. Исследователь HAL
Как это звучит, проводник посвящен изучению новых частей нашего API относительно текущей конечной точки . Он содержит строку поиска, а также текстовые поля для отображения Заголовков пользовательских запросов и свойств текущей конечной точки.
Под ними у нас есть раздел ссылок и кликабельный список встроенных ресурсов.
6.2. Использование ссылок
Если мы перейдем к нашей конечной точке /books , мы сможем просмотреть существующие ссылки:
В этом руководстве мы обсудим, что такое 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:
Если вы строите с помощью Gradle, вы можете добавить эту строку в свой файл build.gradle :
4. Создание простого REST API.
4.1. Простая модель данных
В нашем примере мы настроим простой REST API для просмотра различных книг в нашей библиотеке.
Здесь мы определяем простую сущность книги, которая содержит соответствующие аннотации, чтобы мы могли сохранять данные с помощью Hibernate:
4.2. Представляем CRUD репозиторий
Далее нам понадобятся конечные точки. Для этого мы можем использовать PagingAndSortingRepository и указать, что мы хотим получать данные из нашей сущности Book .
Этот класс предоставляет простые команды CRUD, а также возможности разбиения по страницам и сортировки прямо из коробки:
Если это выглядит немного странно или если вы хотите узнать больше о Spring Repositories, вы можете прочитать больше здесь.
Мы расширили репозиторий, добавив две новые конечные точки:
- findByTitleContain - возвращает книги, содержащие запрос, включенный в заголовок
- findByAuthorContain - возвращает книги из базы данных, в которой автор книги содержит запрос
Обратите внимание, что наша вторая конечная точка содержит атрибут export = false . Этот атрибут останавливает создание ссылок HAL для этой конечной точки и не будет доступен через браузер HAL.
Наконец, мы загрузим наши данные при запуске Spring, определив класс, реализующий интерфейс ApplicationRunner . Вы можете найти код на GitHub.
5. Установка браузера HAL
Настройка браузера HAL очень проста при создании REST API с помощью Spring. Пока у нас есть зависимость, Spring автоматически настроит браузер и сделает его доступным через конечную точку по умолчанию.
Все, что нам нужно сделать сейчас, это нажать «запустить» и переключиться в браузер. После этого браузер HAL будет доступен на // localhost: 8080 /
6. Изучение нашего REST API с помощью браузера HAL
HAL браузер разбиваются на две части - исследователь и инспектор . Мы разберем и исследуем каждый раздел отдельно.
6.1. HAL Explorer
Как кажется, проводник посвящен изучению новых частей нашего API относительно текущей конечной точки . Он содержит панель поиска, а также текстовые поля для отображения настраиваемых заголовков запросов и свойств текущей конечной точки.
Под ними находится раздел ссылок и интерактивный список встроенных ресурсов.
6.2. Использование ссылок
Если мы перейдем к нашей конечной точке / books, мы сможем просмотреть существующие ссылки:
Эти ссылки генерируются из HAL в соседнем разделе:
If we move to the search endpoint, we can also view the custom endpoints we created using the PagingAndSortingRepository:
The HAL above shows our title-contains endpoint displaying suitable search criteria. Note how the author-contains endpoint is missing since we defined that it should not be exported.
6.3. Viewing Embedded Resources
Embedded Resources show the details of the individual book records on our /books endpoint. Each resource also contains its own Properties and Links section:
6.4. Using Forms
The question mark button in the GET column within the links section denotes that a form modal can be used to enter custom search criteria.
Here is the form for our title-contains endpoint:
Our custom URI returns the first page of 20 books where the title contains the word ‘Java'.
6.5. The Hal Inspector
The inspector makes up the right side of the browser and contains the Response Headers and Response Body. This HAL data is used to render the Links and Embedded Resources that we saw earlier in the tutorial.
7. Conclusion
In this article, we've summarised what HAL is, why it's useful and why it can help us to create superior self-documenting REST APIs.
Мы создали простой REST API с помощью Spring, который реализует PagingAndSortingRepository , а также определяет наши собственные конечные точки. Мы также видели, как исключить определенные конечные точки из браузера HAL .
После определения нашего API мы заполнили его тестовыми данными и подробно изучили с помощью браузера HAL. Мы увидели, как устроен браузер HAL, и элементы управления пользовательского интерфейса, которые позволили нам пройти через API и изучить его данные.
Читайте также: