Spring REST og HAL-browser

REST Top

Jeg har lige annonceret det nye Lær foråret kursus med fokus på det grundlæggende i Spring 5 og Spring Boot 2:

>> KONTROLLER KURSEN

1. Oversigt

I denne vejledning diskuterer vi hvad HAL er, og hvorfor det er nyttigt, før du introducerer HAL-browseren.

Vi bruger derefter Spring til at opbygge en simpel REST API med et par interessante slutpunkter og udfylde vores database med nogle testdata.

Endelig, ved hjælp af HAL-browseren, undersøger vi vores REST API og opdager, hvordan vi krydser dataene indeholdt i.

2. HAL og HAL-browseren

JSON Hypertext Application Language eller HAL er et simpelt format giver en konsekvent og nem måde at hyperlinke mellem ressourcer i vores API. Inkludering af HAL i vores REST API gør det meget mere udforskeligt for brugerne såvel som i det væsentlige selvdokumenterende.

Det fungerer ved at returnere data i JSON-format, som skitserer relevant information om API'en.

Det HAL-modellen drejer sig om to enkle koncepter.

Ressourcer, som indeholder:

  • Links til relevante URI'er
  • Indlejrede ressourcer
  • Stat

Links:

  • En mål-URI
  • En relation, eller rel, til linket
  • Et par andre valgfrie egenskaber til at hjælpe med afskrivninger, indholdsforhandling osv

HAL-browseren blev oprettet af den samme person, der udviklede HAL og giver en GUI i browseren til at krydse din REST API.

Vi bygger nu en simpel REST API, tilslutter HAL-browseren og udforsker funktionerne.

3. Afhængigheder

Nedenfor er den enkelte afhængighed, der er nødvendig for at integrere HAL-browseren i vores REST API. Du kan finde resten af ​​afhængighederne til API'et i GitHub-koden.

For det første afhængigheden af ​​Maven-baserede projekter:

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

Hvis du bygger med Gradle, kan du tilføje denne linje til din build.gradle fil:

kompilere gruppe: 'org.springframework.data', navn: 'spring-data-rest-hal-browser', version: '3.0.8.RELEASE'

4. Opbygning af en simpel REST API

4.1. Enkel datamodel

I vores eksempel opretter vi en simpel REST API til at gennemse forskellige bøger i vores bibliotek.

Her definerer vi en simpel bogenhed, der indeholder passende kommentarer, så vi kan fortsætte dataene med dvale:

@Entity public class Book {@Id @GeneratedValue (strategi = GenerationType.IDENTITY) privat lang id; @NotNull @Column (columnDefinition = "VARCHAR", længde = 100) privat streng titel; @NotNull @Column (columnDefinition = "VARCHAR", længde = 100) privat Stringforfatter; @Column (columnDefinition = "VARCHAR", længde = 1000) privat String blurb; private int sider; // sædvanlige getters, settere og konstruktører}

4.2. Introduktion til et CRUD-arkiv

Derefter har vi brug for nogle slutpunkter. For at gøre dette kan vi udnytte PagingAndSortingRepositoryog specificer, at vi vil hente data fra vores Bestil enhed.

Denne klasse giver enkle CRUD-kommandoer samt personsøgnings- og sorteringsfunktioner lige ud af kassen:

@Repository offentlig grænseflade BookRepository udvider PagingAndSortingRepository {@RestResource (rel = "titel-indeholder", sti = "titel-indeholder") Side findByTitleContaining (@Param ("forespørgsel") Strengeforespørgsel, side, side); @RestResource (rel = "forfatter-indeholder", sti = "forfatter-indeholder", eksporteret = falsk) Side findByAuthorContaining (@Param ("forespørgsel") Strengeforespørgsel, side, side); }

Hvis dette ser lidt underligt ud, eller hvis du gerne vil vide mere om Spring Repositories, kan du læse mere her.

Vi har udvidet lageret ved at tilføje to nye slutpunkter:

  • findByTitleContaining - returnerer bøger, der indeholder forespørgslen, der er inkluderet i titlen
  • findByAuthorContaining - returnerer bøger fra databasen, hvor forfatteren af ​​en bog indeholder forespørgslen

Bemærk, at vores andet slutpunkt indeholder eksport = falsk attribut. Denne attribut stopper HAL-links, der genereres til dette slutpunkt, og er ikke tilgængelig via HAL-browseren.

Endelig indlæser vi vores data, når Spring startes ved at definere en klasse, der implementerer ApplicationRunner interface. Du kan finde koden på GitHub.

5. Installation af HAL-browseren

Opsætningen til HAL-browseren er bemærkelsesværdig let, når man bygger en REST API med Spring. Så længe vi har afhængighed, konfigurerer Spring automatisk browseren og gør den tilgængelig via standardendepunktet.

Alt hvad vi skal gøre nu er at trykke på kør og skifte til browseren. HAL-browseren vil derefter være tilgængelig den // localhost: 8080 /

6. Udforskning af vores REST API med HAL-browseren

Det HAL-browseren er opdelt i to dele - opdagelsesrejsende og inspektør. Vi nedbryder og udforsker hvert afsnit separat.

6.1. HAL Explorer

Som det lyder, er udforskeren helliget udforske nye dele af vores API i forhold til det aktuelle slutpunkt. Den indeholder en søgefelt samt tekstfelter, der skal vises Tilpassede anmodningsoverskrifter og egenskaber af det aktuelle slutpunkt.

Under disse har vi linksafsnittet og en klikbar liste over indlejrede ressourcer.

6.2. Brug af links

Hvis vi navigerer til vores /bøger slutpunkt kan vi se de eksisterende links:

Disse links genereres fra HAL i det tilstødende afsnit:

"_links": {"first": {"href": "// localhost: 8080 / books? page = 0 & size = 20"}, "self": {"href": "// localhost: 8080 / books {? side, størrelse, sortering} "," skabeloneret ": sand}," næste ": {" href ":" // localhost: 8080 / books? page = 1 & size = 20 "}," sidste ": {" href ": "// localhost: 8080 / books? page = 4 & size = 20"}, "profile": {"href": "// localhost: 8080 / profile / books"}, "search": {"href": "/ / localhost: 8080 / books / search "}},

Hvis vi flytter til søgeendepunktet, kan vi også se de brugerdefinerede slutpunkter, vi oprettede ved hjælp af PagingAndSortingRepository:

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

HAL ovenfor viser vores titel-indeholder slutpunkt, der viser passende søgekriterier. Bemærk hvordan forfatter-indeholder slutpunkt mangler, da vi definerede, at det ikke skulle eksporteres.

6.3. Visning af indlejrede ressourcer

Indlejrede ressourcer viser detaljer om de enkelte bogoptegnelser på vores /bøger slutpunkt. Hver ressource indeholder også sin egen Ejendomme og Links afsnit:

6.4. Brug af formularer

Spørgsmålstasten i GET-kolonnen i linksafsnittet angiver, at en formmodal kan bruges til at indtaste brugerdefinerede søgekriterier.

Her er formularen til vores titel-indeholder slutpunkt:

Vores brugerdefinerede URI returnerer første side med 20 bøger, hvor titlen indeholder ordet 'Java'.

6.5. Hal-inspektøren

Inspektøren udgør højre side af browseren og indeholder Svarhoveder og responsorgan. Det her HAL-data bruges til at gengive Links og Embedded Resources som vi så tidligere i vejledningen.

7. Konklusion

I denne artikel har vi opsummeret, hvad HAL er, hvorfor det er nyttigt, og hvorfor det kan hjælpe os med at skabe overlegne selvdokumenterende REST API'er.

Vi har bygget en simpel REST API med Spring, der implementerer PagingAndSortingRepositorysamt definere vores egne slutpunkter. Vi har også set hvordan ekskluder visse slutpunkter fra HAL-browseren.

Efter at have defineret vores API, udfyldte vi den med testdata og udforskede den i detaljer ved hjælp af HAL-browseren. Vi så, hvordan HAL-browseren er struktureret, og UI-kontrollerne, der gjorde det muligt for os at gå gennem API'en og udforske dens data.

Som altid er koden tilgængelig på GitHub.

REST bunden

Jeg har lige annonceret det nye Lær foråret kursus med fokus på det grundlæggende i Spring 5 og Spring Boot 2:

>> KONTROLLER KURSEN