Navegador REST e HAL do Spring

1. Visão geral

Neste tutorial, discutiremoswhat HAL is and why it’s useful, before introducing the HAL browser.

Em seguida, usaremos o Spring para construir uma API REST simples com alguns endpoints interessantes e preencher nosso banco de dados com alguns dados de teste.

Finalmente, usando o navegador HAL, exploraremos nossa API REST e descobriremos como atravessar os dados contidos nela.

2. HAL e o navegador HAL

JSON Hypertext Application Language, ou HAL, é um formato simples quegives a consistent and easy way to hyperlink between resources in our API. A inclusão do HAL em nossa API REST torna muito mais explorável para os usuários, além de ser essencialmente autodocumentada.

Ele funciona retornando dados no formato JSON, que descreve informações relevantes sobre a API.

OHAL model revolves around two simple concepts.

Resources, que contém:

Links para URIs relevantes
Recursos Incorporados
Estado

Ligações:

Um URI de destino
Uma relação, ou rel, com o link
Algumas outras propriedades opcionais para ajudar na depreciação, negociação de conteúdo etc.

O navegador HAL foi criado pela mesma pessoa que desenvolveu o HAL eprovides an in-browser GUI to traverse your REST API.

Agora vamos construir uma API REST simples, conectar o navegador HAL e explorar os recursos.

3. Dependências

Abaixo está a dependência única necessária para integrar o navegador HAL à nossa API REST. Você pode encontrar o restante das dependências da API emGitHub code.

Em primeiro lugar,the dependency para projetos baseados em Maven:


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

Se você estiver construindo com o Gradle, poderá adicionar esta linha ao seubuild.gradle file:

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

4. Construindo uma API REST Simples

4.1. Modelo de Dados Simples

Em nosso exemplo, iremos configurar uma API REST simples para navegar por diferentes livros em nossa biblioteca.

Aqui, definimos uma entidade de livro simples que contém anotações apropriadas para que possamos persistir os dados com o 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. Apresentando um Repositório CRUD

Em seguida, precisaremos de alguns terminais. Para fazer isso, podemosleverage the *PagingAndSortingRepository* e especificar que queremos obter dados de nossaBook entity.

Esta classeprovides simple CRUD commands, as well as paging and sorting capabilities pronta para usar:

@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);
}

Se isso parece um pouco estranho, ou se você gostaria de saber mais sobre o Spring Repositories, você pode ler maishere.

Estendemos o repositório adicionando dois novos endpoints:

findByTitleContaining – retorna livros que contenham a consulta incluída no título
findByAuthorContaining – retorna livros do banco de dados onde o autor de um livro contém a consulta

Observe que nossosecond endpoint contains the export = false attribute. Este atributostops the HAL links being generated for this endpoint não estará disponível por meio do navegador HAL.

Finalmente, carregaremos nossos dados quando o Spring for iniciado, definindo uma classe que implementa a interfaceApplicationRunner. Você pode encontrar o código emGitHub.

5. Instalando o Navegador HAL

A configuração do navegador HAL é notavelmente fácil ao criar uma API REST com Spring. Enquanto tivermos a dependência, o Spring configurará automaticamente o navegador e o disponibilizará pelo ponto de extremidade padrão.

Tudo o que precisamos fazer agora é pressionar executar e mudar para o navegador. O navegador HAL estará disponível emhttp://localhost:8080/

6. Explorando nossa API REST com o navegador HAL

OHAL browser is broken down into two parts – the explorer and the inspector. Vamos dividir e explorar cada seção separadamente.

6.1. O HAL Explorer

Ao que parece, o explorador é dedicado aexploring new parts of our API relative to the current endpoint. Ele contém uma barra de pesquisa, bem como caixas de texto para exibirCustom Request Headers and Properties do terminal atual.

Abaixo desses, temos a seção de links e uma lista clicável de Recursos incorporados.

6.2. Usando Links

Se navegarmos para o nosso/books ponto de envio, podemos ver os links existentes:

Esteslinks are generated from the HAL na seção adjacente:

"_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"
    }
  },

Se movermos para o endpoint de pesquisa, também podemos visualizar os endpoints personalizados que criamos usando oPagingAndSortingRepository:

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

O HAL acima mostra nossotitle-contains endpoint displaying suitable search criteria. Observe como o ponto finalauthor-contains está faltando, pois definimos que ele não deve ser exportado.

6.3. Exibindo recursos incorporados

Os recursos incorporados mostramdetails of the individual book records em nosso ponto de extremidade/books. Cada recurso também contém sua própria seçãoProperties andLinks :

6.4. Usando formulários

O botão de ponto de interrogação na coluna GET na seção de links indica que um modal de formulário pode ser usado para inserir critérios de pesquisa personalizados.

Aqui está o formulário para nossotitle-contains ponto de envio:

The HAL browser selection form

Nosso URI personalizado retorna ofirst page of 20 books where the title contains the word ‘Java'.

6.5. The Hal Inspector

O inspetor fica no lado direito do navegador e contémResponse Headers and Response Body. ThisHAL data is used to render the Links and Embedded Resources que vimos anteriormente no tutorial.

7. Conclusão

Neste artigo, resumimos o que é HAL, por que é útil e por que pode nos ajudar a criarsuperior self-documenting REST APIs.

Construímos uma API REST simples com Spring que implementaPagingAndSortingRepository, bem como definimos nossos próprios terminais. Também vimos comoexclude certain endpoints from the HAL browser.

Depois de definir nossa API, a preenchemos com dados de teste e a exploramos em detalhes com a ajuda do navegador HAL. Vimos como o navegador HAL está estruturado e a interface do usuário controla, o que nos permitiu percorrer a API e explorar seus dados.

Como sempre, o código está disponívelover on GitHub.

TOC

Navegador REST e HAL do Spring