TOC

Spring REST и HAL Browser

Spring REST и HAL Browser

1. обзор

В этом руководстве мы обсудимwhat HAL is and why it’s useful, before introducing the HAL browser.

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

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

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

JSON Hypertext Application Language или HAL - это простой формат, в которомgives a consistent and easy way to hyperlink between resources in our API. Включение HAL в наш REST API делает его гораздо более удобным для пользователей, а также по сути самодокументируемым.

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

HAL model revolves around two simple concepts.

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

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

  • Встроенные ресурсы

  • государственный

Ссылки:

  • Целевой URI

  • Отношение, или rel, к ссылке

  • Несколько других необязательных свойств, которые помогут с амортизацией, согласованием контента и т. Д.

Браузер HAL был создан тем же человеком, который разработал HAL иprovides an in-browser GUI to traverse your REST API.

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

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

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

Во-первых,the dependency для проектов на основе Maven: 


    org.springframework.data
    spring-data-rest-hal-browser
    3.0.8.RELEASE

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

compile group: 'org.springframework.data', name: 'spring-data-rest-hal-browser', version: '3.0.8.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-репозиторий

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

Этот классprovides simple CRUD commands, as well as paging and sorting capabilities прямо из коробки: 

@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 Repositories, вы можете прочитать большеhere.

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

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

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

Обратите внимание, что нашsecond endpoint contains the export = false attribute. Этот атрибутstops the HAL links being generated for this endpoint не будет доступен через браузер HAL.

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

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

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

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

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

HAL browser is broken down into two parts – the explorer and the inspector. Мы разберем и исследуем каждый раздел отдельно.

6.1. HAL Explorer

Как бы то ни было, проводник посвященexploring new parts of our API relative to the current endpoint. Он содержит панель поиска, а также текстовые поля для отображенияCustom Request Headers and Properties текущей конечной точки.

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

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

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

image

Этиlinks are generated from the 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-contains endpoint displaying suitable search criteria.. Обратите внимание, что конечная точкаauthor-contains отсутствует, поскольку мы определили, что ее не следует экспортировать.

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

Встроенные ресурсы показываютdetails of the individual book records на нашей конечной точке/books. Каждый ресурс также содержит свой собственный разделProperties andLinks :

image

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

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

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

The HAL browser selection form

Наш настраиваемый URI возвращаетfirst page of 20 books where the title contains the word ‘Java'.

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

Инспектор составляет правую часть браузера и содержитResponse Headers and Response Body. ThisHAL data is used to render the Links and Embedded Resources , которые мы видели ранее в руководстве.

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

В этой статье мы кратко описали, что такое HAL, почему он полезен и почему он может помочь нам создатьsuperior self-documenting REST APIs.

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

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

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

Related