streamalism.org

Jeg kunngjorde nettopp det nye Lær våren kurs, med fokus på det grunnleggende i vår 5 og vårstøvel 2:

1. Oversikt

I denne opplæringen skal vi diskutere hva HAL er og hvorfor det er nyttig før du introduserer HAL-nettleseren.

Vi bruker deretter Spring til å bygge en enkel REST API med noen få interessante sluttpunkter og fylle ut databasen vår med noen testdata.

Til slutt, ved hjelp av HAL-nettleseren, vil vi utforske REST API og finne ut hvordan vi kan krysse dataene som finnes i.

2. HAL og HAL-nettleseren

JSON Hypertext Application Language, eller HAL, er et enkelt format som gir en jevn og enkel måte å hyperkoble mellom ressurser i API-et vårt. Inkludering av HAL i REST API gjør det mye mer utforskbart for brukere, så vel som i det vesentlige selvdokumenterende.

Det fungerer ved å returnere data i JSON-format som skisserer relevant informasjon om API.

De HAL-modellen dreier seg om to enkle konsepter.

Ressurser, som inneholder:

• Lenker til relevante URIer
• Innebygde ressurser
• Stat

Lenker:

• En mål-URI
• En relasjon, eller rel, til lenken
• Noen få andre valgfrie egenskaper som hjelper til med avskrivninger, innholdsforhandlinger osv

HAL-nettleseren ble opprettet av den samme personen som utviklet HAL og gir en GUI i nettleseren for å krysse REST API.

Vi bygger nå en enkel REST API, plugger inn HAL-nettleseren og utforsker funksjonene.

3. Avhengigheter

Nedenfor er den eneste avhengigheten som trengs for å integrere HAL-nettleseren i vår REST API. Du finner resten av avhengighetene for API i GitHub-koden.

For det første avhengigheten av Maven-baserte prosjekter:

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

Hvis du bygger med Gradle, kan du legge til denne linjen i din build.gradle fil:

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

4. Å bygge en enkel REST API

4.1. Enkel datamodell

I vårt eksempel setter vi opp en enkel REST API for å bla gjennom forskjellige bøker i biblioteket vårt.

Her definerer vi en enkel bokenhet som inneholder passende kommentarer, slik at vi kan vedvare dataene med dvalemodus:

@Entity public class Bestill {@Id @GeneratedValue (strategi = GenerationType.IDENTITY) privat lang id; @NotNull @Column (columnDefinition = "VARCHAR", lengde = 100) privat streng tittel; @NotNull @Column (columnDefinition = "VARCHAR", length = 100) privat strengforfatter; @Column (columnDefinition = "VARCHAR", lengde = 1000) privat String uskarphet; private int sider; // vanlige getters, setters og konstruktører}

4.2. Vi introduserer et CRUD Repository

Deretter trenger vi noen endepunkter. For å gjøre dette kan vi utnytte PagingAndSortingRepositoryog spesifiser at vi ønsker å få data fra vår Bok enhet.

Denne klassen gir enkle CRUD-kommandoer, samt personsøkings- og sorteringsfunksjoner rett ut av esken:

@Repository offentlig grensesnitt BookRepository utvider PagingAndSortingRepository {@RestResource (rel = "title-contains", path = "title-contains") Side findByTitleContaining (@Param ("spørring") Strengespørsmål, Sideside); @RestResource (rel = "forfatter-inneholder", sti = "forfatter-inneholder", eksportert = falsk) Side findByAuthorContaining (@Param ("spørring") Strengespørsmål, side med side); }

Hvis dette ser litt rart ut, eller hvis du vil vite mer om Spring Repositories, kan du lese mer her.

Vi har utvidet depotet ved å legge til to nye sluttpunkter:

• findByTitleContaining - returnerer bøker som inneholder spørringen som er inkludert i tittelen
• findByAuthorContaining - returnerer bøker fra databasen der forfatteren av en bok inneholder spørringen

Merk at vår det andre endepunktet inneholder eksport = usann Egenskap. Denne egenskapen stopper HAL-koblingene som genereres for dette endepunktet, og vil ikke være tilgjengelig via HAL-nettleseren.

Til slutt vil vi laste inn dataene våre når våren startes ved å definere en klasse som implementerer ApplicationRunner grensesnitt. Du finner koden på GitHub.

5. Installere HAL-nettleseren

Oppsettet for HAL-nettleseren er utrolig enkelt når du bygger en REST API med Spring. Så lenge vi har avhengighet, konfigurerer Spring nettleseren automatisk og gjør den tilgjengelig via standard endepunkt.

Alt vi trenger å gjøre nå er å trykke på kjør og bytte til nettleseren. HAL-nettleseren vil da være tilgjengelig på // lokal vert: 8080 /

6. Utforske REST API med HAL-nettleseren

De HAL-nettleseren er delt inn i to deler - utforskeren og inspektøren. Vi vil bryte sammen og utforske hver seksjon separat.

6.1. HAL Explorer

Som det høres ut, er utforskeren viet til utforske nye deler av API-en vår i forhold til gjeldende endepunkt. Den inneholder en søkefelt, samt tekstfelt å vise Tilpassede forespørselsoverskrifter og egenskaper av gjeldende endepunkt.

Under disse har vi lenkeseksjonen og en klikkbar liste over innebygde ressurser.

6.2. Bruke lenker

Hvis vi navigerer til vår / bøker sluttpunkt kan vi se de eksisterende koblingene:

Disse koblinger genereres fra HAL i tilstøtende seksjon:

"_links": {"first": {"href": "// localhost: 8080 / books? page = 0 & size = 20"}, "self": {"href": "// localhost: 8080 / books {? side, størrelse, sortering} "," templated ": true}," neste ": {" 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 "}},

Hvis vi går til søkeendepunktet, kan vi også se de egendefinerte endepunktene vi opprettet ved hjelp av 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 vår tittel inneholder sluttpunkt som viser passende søkekriterier. Legg merke til hvordan inneholder forfatter endepunkt mangler siden vi definerte at det ikke skulle eksporteres.

6.3. Vise innebygde ressurser

Embedded Resources viser detaljer om de enkelte bokoppføringene på vår / bøker endepunkt. Hver ressurs inneholder også sine egne Eiendommer og Lenker seksjon:

6.4. Bruke skjemaer

Spørsmålstegneknappen i GET-kolonnen i lenkeseksjonen angir at et skjemamodal kan brukes til å angi tilpassede søkekriterier.

Her er skjemaet for vårt tittel inneholder sluttpunkt:

Vår tilpassede URI returnerer første side på 20 bøker der tittelen inneholder ordet ‘Java’.

6.5. Hal-inspektøren

Inspektøren utgjør høyre side av nettleseren og inneholder Responsoverskrifter og responsorgan. Dette HAL-data brukes til å gjengi koblinger og innebygde ressurser som vi så tidligere i veiledningen.

7. Konklusjon

I denne artikkelen har vi oppsummert hva HAL er, hvorfor det er nyttig og hvorfor det kan hjelpe oss å lage overlegne selvdokumenterende REST APIer.

Vi har bygget en enkel REST API med Spring som implementerer PagingAndSortingRepository, samt å definere våre egne endepunkter. Vi har også sett hvordan ekskluder visse endepunkter fra HAL-nettleseren.

Etter å ha definert API-en vår fylte vi den med testdata og utforsket den i detalj ved hjelp av HAL-nettleseren. Vi så hvordan HAL-nettleseren er strukturert, og brukergrensesnittkontrollene som tillot oss å gå gjennom API-et og utforske dataene.

Som alltid er koden tilgjengelig på GitHub.

Jeg kunngjorde nettopp det nye Lær våren kurs, med fokus på det grunnleggende i vår 5 og vårstøvel 2: