streamalism.org

Ik heb zojuist het nieuwe aangekondigd Leer de lente natuurlijk, gericht op de basisprincipes van Spring 5 en Spring Boot 2:

1. Overzicht

In deze tutorial bespreken we wat HAL is en waarom het nuttig is, voordat de HAL-browser wordt geïntroduceerd.

Vervolgens gebruiken we Spring om een ​​eenvoudige REST API te bouwen met een paar interessante eindpunten en vullen we onze database met wat testgegevens.

Ten slotte zullen we met behulp van de HAL-browser onze REST API verkennen en ontdekken hoe we de gegevens erin kunnen doorzoeken.

2. HAL en de HAL-browser

JSON Hypertext Application Language, of HAL, is een eenvoudig formaat dat biedt een consistente en gemakkelijke manier om een ​​hyperlink te maken tussen bronnen in onze API. Door HAL op te nemen in onze REST API, wordt het veel beter verkenbaar voor gebruikers en is het in wezen zelfdocumenterend.

Het werkt door gegevens in JSON-indeling te retourneren die relevante informatie over de API schetst.

De Het HAL-model draait om twee eenvoudige concepten.

Middelen, die bevatten:

• Links naar relevante URI's
• Ingebouwde bronnen
• Staat

Links:

• Een doel-URI
• Een relatie of rel met de link
• Een paar andere optionele eigendommen om te helpen bij afschrijving, onderhandeling over de inhoud, enz

De HAL-browser is gemaakt door dezelfde persoon die HAL en biedt een in-browser GUI om uw REST API te doorlopen.

We gaan nu een eenvoudige REST API bouwen, de HAL-browser aansluiten en de functies verkennen.

3. Afhankelijkheden

Hieronder vindt u de enige afhankelijkheid die nodig is om de HAL-browser te integreren in onze REST API. Je kunt de rest van de afhankelijkheden voor de API vinden in de GitHub-code.

Ten eerste de afhankelijkheid voor op Maven gebaseerde projecten:

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

Als je met Gradle bouwt, kun je deze regel toevoegen aan je build.gradle het dossier:

compileer groep: 'org.springframework.data', naam: 'spring-data-rest-hal-browser', versie: '3.0.8.RELEASE'

4. Het bouwen van een eenvoudige REST API

4.1. Eenvoudig gegevensmodel

In ons voorbeeld zullen we een eenvoudige REST API opzetten om door verschillende boeken in onze bibliotheek te bladeren.

Hier definiëren we een eenvoudige boekentiteit die de juiste annotaties bevat, zodat we de gegevens met Hibernate kunnen behouden:

@Entity public class Book {@Id @GeneratedValue (strategy = GenerationType.IDENTITY) privé lang ID; @NotNull @Column (columnDefinition = "VARCHAR", length = 100) private String-titel; @NotNull @Column (columnDefinition = "VARCHAR", lengte = 100) privé String-auteur; @Column (columnDefinition = "VARCHAR", length = 1000) private String blurb; privé int-pagina's; // gebruikelijke getters, setters en constructeurs}

4.2. Introductie van een CRUD-repository

Vervolgens hebben we enkele eindpunten nodig. Om dit te doen, kunnen we gebruik maken van de PagingAndSortingRepositoryen specificeren dat we gegevens van onze Boek entiteit.

Deze klas biedt eenvoudige CRUD-opdrachten, evenals paging- en sorteermogelijkheden direct uit de doos:

@Repository openbare interface BookRepository breidt PagingAndSortingRepository uit {@RestResource (rel = "title-bevat", pad = "titel-bevat") Pagina findByTitleContaining (@Param ("query") Stringquery, Paginabevattende pagina); @RestResource (rel = "author-contains", path = "author-contains", geëxporteerd = false) Pagina findByAuthorContaining (@Param ("query") String-query, pagineerbare pagina); }

Als dit een beetje vreemd lijkt, of als je meer wilt weten over Spring Repositories, kun je hier meer lezen.

We hebben de repository uitgebreid door twee nieuwe eindpunten toe te voegen:

• findByTitleContaining - geeft boeken terug die de zoekopdracht bevatten die in de titel is opgenomen
• findByAuthorContaining - geeft boeken terug uit de database waarin de auteur van een boek de zoekopdracht bevat

Merk op dat onze tweede eindpunt bevat het export = false attribuut. Dit kenmerk stopt de HAL-links die voor dit eindpunt worden gegenereerd, en zal niet beschikbaar zijn via de HAL-browser.

Ten slotte laden we onze gegevens wanneer Spring wordt gestart door een klasse te definiëren die het ToepassingRunner koppel. Je kunt de code vinden op GitHub.

5. De HAL-browser installeren

De setup voor de HAL-browser is opmerkelijk eenvoudig bij het bouwen van een REST API met Spring. Zolang we de afhankelijkheid hebben, zal Spring de browser automatisch configureren en beschikbaar maken via het standaard eindpunt.

Het enige dat we nu hoeven te doen, is op run drukken en naar de browser overschakelen. De HAL-browser is dan beschikbaar op // localhost: 8080 /

6. Onze REST API verkennen met de HAL-browser

De De HAL-browser is onderverdeeld in twee delen: de verkenner en de inspecteur. We zullen elke sectie afzonderlijk opsplitsen en verkennen.

6.1. De HAL Explorer

Zoals het klinkt, is de ontdekkingsreiziger toegewijd aan het verkennen van nieuwe delen van onze API ten opzichte van het huidige eindpunt. Het bevat een zoekbalk en tekstvakken om weer te geven Custom Request Headers en Eigenschappen van het huidige eindpunt.

Hieronder hebben we het gedeelte met links en een klikbare lijst met ingesloten bronnen.

6.2. Links gebruiken

Als we naar onze /boeken eindpunt kunnen we de bestaande links bekijken:

Deze links worden gegenereerd vanuit de HAL in de aangrenzende sectie:

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

Als we naar het zoekeindpunt gaan, kunnen we ook de aangepaste eindpunten bekijken die we hebben gemaakt met de PagingAndSortingRepository:

{"_links": {"titel-bevat": {"href": "// localhost: 8080 / boeken / zoeken / titel-bevat {? zoekopdracht, pagina, grootte, sortering}", "sjabloon": true}, "self": {"href": "// localhost: 8080 / books / search"}}} 

De HAL hierboven toont onze titel-bevat eindpunt met geschikte zoekcriteria. Merk op hoe de auteur-bevat endpoint ontbreekt omdat we hebben gedefinieerd dat het niet mag worden geëxporteerd.

6.3. Ingebouwde bronnen bekijken

Ingesloten bronnen tonen het details van de individuele boekrecords op onze /boeken eindpunt. Elke bron bevat ook zijn eigen Eigendommen en Links sectie:

6.4. Formulieren gebruiken

De vraagtekenknop in de GET-kolom in de koppelingssectie geeft aan dat een formuliermodaal kan worden gebruikt om aangepaste zoekcriteria in te voeren.

Hier is het formulier voor onze titel-bevat eindpunt:

Onze aangepaste URI retourneert het eerste pagina van 20 boeken waarvan de titel het woord ‘Java 'bevat.

6.5. De Hal-inspecteur

De inspecteur vormt de rechterkant van de browser en bevat de Response Headers en Response Body. Dit HAL-gegevens worden gebruikt om de koppelingen en ingesloten bronnen weer te geven die we eerder in de tutorial zagen.

7. Conclusie

In dit artikel hebben we samengevat wat HAL is, waarom het nuttig is en waarom het ons kan helpen bij het creëren superieure zelfdocumenterende REST API's.

We hebben een eenvoudige REST API gebouwd met Spring die de PagingAndSortingRepository, evenals het definiëren van onze eigen eindpunten. We hebben ook gezien hoe sluit bepaalde eindpunten uit van de HAL-browser.

Nadat we onze API hadden gedefinieerd, hebben we deze gevuld met testgegevens en deze in detail onderzocht met behulp van de HAL-browser. We hebben gezien hoe de HAL-browser is gestructureerd en de UI-besturingselementen waarmee we door de API konden stappen en de gegevens ervan konden verkennen.

Zoals altijd is de code beschikbaar op GitHub.

Ik heb zojuist het nieuwe aangekondigd Leer de lente natuurlijk, gericht op de basisprincipes van Spring 5 en Spring Boot 2: