Jarný prehliadač REST a HAL
Práve som oznámil nové Naučte sa jar kurz zameraný na základy jari 5 a Spring Boot 2:
>> SKONTROLUJTE KURZ1. Prehľad
V tejto príručke budeme diskutovať čo je to HAL a prečo je to užitočné, skôr ako predstavíme prehliadač HAL.
Potom pomocou Spring zostavíme jednoduché REST API s niekoľkými zaujímavými koncovými bodmi a naplníme našu databázu niekoľkými testovacími údajmi.
Na záver pomocou prehliadača HAL preskúmame naše rozhranie REST API a zistíme, ako prechádzať obsiahnutými údajmi.
2. HAL a prehliadač HAL
Hypertextový aplikačný jazyk JSON alebo HAL je jednoduchý formát, ktorý poskytuje konzistentný a ľahký spôsob hypertextového odkazu medzi zdrojmi v našom API. Zahrnutie HAL do nášho rozhrania REST API umožňuje používateľom urobiť ho oveľa prehľadnejším a v podstate samodokumentujúcim.
Funguje to tak, že vraciate údaje vo formáte JSON, ktorý načrtáva príslušné informácie o API.
The Model HAL sa točí okolo dvoch jednoduchých konceptov.
Zdroje, ktoré obsahujú:
- Odkazy na príslušné URI
- Vložené zdroje
- Štát
Odkazy:
- Cieľový identifikátor URI
- Vzťah alebo odkaz k odkazu
- Niekoľko ďalších voliteľných vlastností, ktoré uľahčujú odpisovanie, vyjednávanie obsahu atď
Prehliadač HAL vytvoril ten istý človek, ktorý vyvinul HAL a poskytuje v prehliadači grafické používateľské rozhranie na prechádzanie rozhraním REST API.
Teraz zostavíme jednoduché rozhranie REST API, zapojíme prehliadač HAL a preskúmame funkcie.
3. Závislosti
Ďalej uvádzame jednu závislosť potrebnú na integráciu prehľadávača HAL do nášho rozhrania REST API. Zvyšok závislostí pre API nájdete v kóde GitHub.
Po prvé, závislosť pre projekty založené na Maven:
org.springframework.data spring-data-rest-hal-browser 3.2.6.RELEASE Ak staviate s programom Gradle, môžete tento riadok pridať do svojho súboru build.gradle spis:
skupina kompilácií: „org.springframework.data“, názov: „spring-data-rest-hal-browser“, verzia: „3.0.8.RELEASE“4. Vytvorenie jednoduchého rozhrania REST API
4.1. Jednoduchý dátový model
V našom príklade nastavujeme jednoduché rozhranie REST API na prehliadanie rôznych kníh v našej knižnici.
Tu definujeme jednoduchú entitu knihy, ktorá obsahuje príslušné anotácie, aby sme mohli údaje uchovať pomocou režimu dlhodobého spánku:
@Entity public class Book {@Id @GeneratedValue (strategy = GenerationType.IDENTITY) private long id; @NotNull @Column (columnDefinition = "VARCHAR", dĺžka = 100) názov súkromného reťazca; @NotNull @Column (columnDefinition = "VARCHAR", dĺžka = 100) súkromný autor reťazca; @Column (columnDefinition = "VARCHAR", dĺžka = 1000) súkromná reklama s reťazcami; súkromné int stránky; // obvyklí tvorcovia, zakladatelia a konštruktéri}4.2. Predstavujeme úložisko CRUD
Ďalej budeme potrebovať nejaké koncové body. Aby sme to dosiahli, môžeme využiť PagingAndSortingRepositorya upresnite, že chceme získať údaje z nášho Kniha subjekt.
Táto trieda poskytuje jednoduché príkazy CRUD, ako aj možnosti stránkovania a triedenia hneď po vybalení z krabice:
@Repository verejné rozhranie BookRepository rozširuje PagingAndSortingRepository {@RestResource (rel = "title-contains", path = "title-contains") Stránka findByTitleContaining (@Param ("query") reťazcový dotaz, stránkovateľná stránka); @RestResource (rel = "author-contains", path = "author-contains", exported = false) stránka findByAuthorContaining (@Param ("query") reťazcový dotaz, stránkovateľná stránka); }Ak to vyzerá trochu divne alebo ak sa chcete o Jarných úložiskách dozvedieť viac, môžete si prečítať viac tu.
Rozšírili sme úložisko pridaním dvoch nových koncových bodov:
- findByTitleContaining - vráti knihy, ktoré obsahujú dopyt zahrnutý v názve
- findByAuthorContaining - vráti knihy z databázy, v ktorej autor knihy obsahuje dopyt
Všimnite si, že naše druhý koncový bod obsahuje export = nepravda atribút. Tento atribút zastaví generovanie odkazov HAL pre tento koncový bod, a nebudú dostupné prostredníctvom prehľadávača HAL.
Nakoniec načítame naše údaje, keď sa Spring začne definovaním triedy, ktorá implementuje ApplicationRunner rozhranie. Kód nájdete na GitHub.
5. Inštalácia prehľadávača HAL
Nastavenie prehľadávača HAL je pozoruhodne ľahké pri vytváraní rozhrania REST API s pružinou. Pokiaľ máme závislosť, Spring automaticky nakonfiguruje prehliadač a sprístupní ho prostredníctvom predvoleného koncového bodu.
Všetko, čo musíme urobiť, je stlačiť run a prepnúť na prehliadač. Prehliadač HAL bude potom k dispozícii na // localhost: 8080 /
6. Preskúmanie nášho rozhrania REST API pomocou prehľadávača HAL
The Prehliadač HAL je rozdelený na dve časti - prieskumník a inšpektor. Rozoberieme to a preskúmame každú časť zvlášť.
6.1. Prieskumník HAL
Ako to znie, prieskumníkovi je oddaný skúmanie nových častí nášho API vo vzťahu k aktuálnemu koncovému bodu. Obsahuje vyhľadávací panel a tiež textové polia na zobrazenie Hlavičky a vlastnosti vlastných požiadaviek aktuálneho koncového bodu.
Pod nimi máme sekciu s odkazmi a klikateľný zoznam vložených zdrojov.
6.2. Používanie odkazov
Ak sa navigujeme k nášmu / knihy koncový bod si môžeme prezrieť existujúce odkazy:
Títo odkazy sú generované z HAL v susednej časti:
"_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 "}},Ak sa presunieme do koncového bodu vyhľadávania, môžeme si tiež pozrieť vlastné koncové body, ktoré sme vytvorili pomocou PagingAndSortingRepository:
{"_links": {"title-contains": {"href": "// localhost: 8080 / books / search / title-contains {? dopyt, stránka, veľkosť, triedenie}", "templated": true}, "self": {"href": "// localhost: 8080 / books / search"}}} HAL vyššie ukazuje našu nadpis-obsahuje koncový bod zobrazujúci vhodné kritériá vyhľadávania. Všimnite si, ako autor-obsahuje koncový bod chýba, pretože sme definovali, že by sa nemal exportovať.
6.3. Prezeranie vložených zdrojov
Vložené zdroje ukazujú podrobnosti o jednotlivých knižných záznamoch na našom / knihy koncový bod. Každý zdroj obsahuje aj svoj vlastný Vlastnosti a Odkazy časť:
6.4. Používanie formulárov
Tlačidlo otáznika v stĺpci GET v sekcii odkazov označuje, že na zadanie vlastných vyhľadávacích kritérií je možné použiť modálny formulár.
Tu je formulár pre naše nadpis-obsahuje koncový bod:
Náš vlastný URI vracia prvá strana 20 kníh, ktorých názov obsahuje slovo „Java“.
6.5. Hal inšpektor
Inšpektor tvorí pravú stranu prehliadača a obsahuje Hlavičky a telo odpovede. Toto Údaje HAL sa používajú na vykreslenie odkazov a vložených zdrojov ktoré sme videli skôr v tutoriále.
7. Záver
V tomto článku sme zhrnuli, čo je HAL, prečo je užitočný a prečo nám môže pomôcť pri tvorbe vynikajúce samodokumentujúce rozhrania REST API.
S Springom sme vytvorili jednoduché REST API, ktoré implementuje PagingAndSortingRepository, ako aj definovanie vlastných koncových bodov. Tiež sme videli, ako na to vylúčiť určité koncové body z prehliadača HAL.
Po definovaní nášho API sme ho naplnili testovacími údajmi a podrobne sme ich preskúmali pomocou prehliadača HAL. Videli sme, ako je prehľadávač HAL štruktúrovaný, a ovládacie prvky používateľského rozhrania, ktoré nám umožnili prechádzať API a skúmať jeho údaje.
Ako vždy, kód je k dispozícii na GitHub.
REST spodok
