Acabo de anunciar el nuevo curso Learn Spring , centrado en los fundamentos de Spring 5 y Spring Boot 2:
>> VER EL CURSO1. Información general
En este tutorial, discutiremos qué es HAL y por qué es útil, antes de presentar el navegador HAL .
Luego usaremos Spring para construir una API REST simple con algunos puntos finales interesantes y completar nuestra base de datos con algunos datos de prueba.
Finalmente, usando el navegador HAL, exploraremos nuestra API REST y descubriremos cómo atravesar los datos que contiene.
2. HAL y el navegador HAL
JSON Hypertext Application Language, o HAL, es un formato simple que brinda una manera consistente y fácil de hacer hipervínculos entre los recursos de nuestra API . La inclusión de HAL dentro de nuestra API REST hace que sea mucho más explorable para los usuarios, además de ser esencialmente auto-documentable.
Funciona devolviendo datos en formato JSON que describe información relevante sobre la API.
El modelo HAL gira en torno a dos conceptos simples.
Recursos, que contienen:
- Enlaces a URI relevantes
- Recursos integrados
- Estado
Enlaces:
- Un URI de destino
- Una relación, o rel, con el enlace
- Algunas otras propiedades opcionales para ayudar con la depreciación, la negociación de contenido, etc.
El navegador HAL fue creado por la misma persona que desarrolló HAL y proporciona una GUI en el navegador para recorrer su API REST .
Ahora crearemos una API REST simple, conectaremos el navegador HAL y exploraremos las funciones.
3. Dependencias
A continuación se muestra la dependencia única necesaria para integrar el navegador HAL en nuestra API REST. Puede encontrar el resto de las dependencias de la API en el código de GitHub.
En primer lugar, la dependencia para proyectos basados en Maven:
org.springframework.data spring-data-rest-hal-browser 3.2.6.RELEASE Si está compilando con Gradle, puede agregar esta línea a su archivo build.gradle :
compile group: 'org.springframework.data', name: 'spring-data-rest-hal-browser', version: '3.0.8.RELEASE'4. Creación de una API REST simple
4.1. Modelo de datos simple
En nuestro ejemplo, configuraremos una API REST simple para buscar diferentes libros en nuestra biblioteca.
Aquí, definimos una entidad de libro simple que contiene las anotaciones apropiadas para que podamos conservar los datos con 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. Presentación de un repositorio CRUD
A continuación, necesitaremos algunos puntos finales. Para hacer esto, podemos aprovechar PagingAndSortingRepository y especificar que queremos obtener datos de nuestra entidad Book .
Esta clase proporciona comandos CRUD simples, así como capacidades de paginación y clasificación desde el primer momento:
@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); }Si esto parece un poco extraño, o si desea saber más sobre Spring Repositories, puede leer más aquí.
Hemos ampliado el repositorio agregando dos nuevos puntos finales:
- findByTitleContaining: devuelve libros que contienen la consulta incluida en el título.
- findByAuthorContaining: devuelve libros de la base de datos donde el autor de un libro contiene la consulta
Tenga en cuenta que nuestro segundo punto final contiene el atributo export = false . Este atributo detiene la generación de enlaces HAL para este punto final y no estará disponible a través del navegador HAL.
Finalmente, cargaremos nuestros datos cuando se inicie Spring definiendo una clase que implemente la interfaz ApplicationRunner . Puedes encontrar el código en GitHub.
5. Instalación del navegador HAL
La configuración del navegador HAL es notablemente fácil cuando se crea una API REST con Spring. Siempre que tengamos la dependencia, Spring configurará automáticamente el navegador y lo pondrá a disposición a través del punto final predeterminado.
Todo lo que tenemos que hacer ahora es presionar Ejecutar y cambiar al navegador. El navegador HAL estará disponible en // localhost: 8080 /
6. Exploración de nuestra API REST con el navegador HAL
El navegador HAL se divide en dos partes: el explorador y el inspector . Desglosaremos y exploraremos cada sección por separado.
6.1. El explorador de HAL
Como parece, el explorador se dedica a explorar nuevas partes de nuestra API en relación con el punto final actual . Contiene una barra de búsqueda, así como cuadros de texto para mostrar propiedades y encabezados de solicitud personalizados del punto final actual.
Debajo de estos, tenemos la sección de enlaces y una lista de recursos integrados en los que se puede hacer clic.
6.2. Usando enlaces
Si navegamos hasta nuestro punto final / books , podemos ver los enlaces existentes:
Estos enlaces se generan a partir del HAL en la sección adyacente:
"_links": { "first": { "href": "//localhost:8080/books?page=0&size=20" }, "self": { "href": "//localhost:8080/books{?page,size,sort}", "templated": true }, "next": { "href": "//localhost:8080/books?page=1&size=20" }, "last": { "href": "//localhost:8080/books?page=4&size=20" }, "profile": { "href": "//localhost:8080/profile/books" }, "search": { "href": "//localhost:8080/books/search" } },If we move to the search endpoint, we can also view the custom endpoints we created using the PagingAndSortingRepository:
{ "_links": { "title-contains": { "href": "//localhost:8080/books/search/title-contains{?query,page,size,sort}", "templated": true }, "self": { "href": "//localhost:8080/books/search" } } } 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.
Hemos construido una API REST simple con Spring que implementa PagingAndSortingRepository , además de definir nuestros propios puntos finales. También hemos visto cómo excluir ciertos puntos finales del navegador HAL .
Después de definir nuestra API, la llenamos con datos de prueba y la exploramos en detalle con la ayuda del navegador HAL. Vimos cómo está estructurado el navegador HAL y los controles de la interfaz de usuario que nos permitieron recorrer la API y explorar sus datos.
Como siempre, el código está disponible en GitHub.
DESCANSO inferior