Browser Spring REST e HAL

REST Top

Ho appena annunciato il nuovo corso Learn Spring , incentrato sui fondamenti di Spring 5 e Spring Boot 2:

>> SCOPRI IL CORSO

1. Panoramica

In questo tutorial, discuteremo di cos'è HAL e perché è utile, prima di introdurre il browser HAL .

Utilizzeremo quindi Spring per creare una semplice API REST con alcuni endpoint interessanti e popoleremo il nostro database con alcuni dati di test.

Infine, utilizzando il browser HAL, esploreremo la nostra API REST e scopriremo come attraversare i dati contenuti all'interno.

2. HAL e il browser HAL

JSON Hypertext Application Language, o HAL, è un formato semplice che offre un modo semplice e coerente per il collegamento ipertestuale tra le risorse nella nostra API . Includere HAL nella nostra API REST lo rende molto più esplorabile per gli utenti oltre ad essere essenzialmente auto-documentante.

Funziona restituendo i dati in formato JSON che delinea le informazioni rilevanti sull'API.

Il modello HAL ruota attorno a due semplici concetti.

Risorse, che contengono:

  • Collegamenti a URI pertinenti
  • Risorse incorporate
  • Stato

Collegamenti:

  • Un URI di destinazione
  • Una relazione, o rel, al collegamento
  • Alcune altre proprietà opzionali per aiutare con l'ammortamento, la negoziazione del contenuto, ecc

Il browser HAL è stato creato dalla stessa persona che ha sviluppato HAL e fornisce una GUI nel browser per attraversare la tua API REST .

Ora creeremo una semplice API REST, collegheremo il browser HAL ed esploreremo le funzionalità.

3. Dipendenze

Di seguito è riportata la singola dipendenza necessaria per integrare il browser HAL nella nostra API REST. Puoi trovare il resto delle dipendenze per l'API nel codice GitHub.

In primo luogo, la dipendenza per i progetti basati su Maven:

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

Se stai costruendo con Gradle, puoi aggiungere questa riga al tuo file build.gradle :

compile group: 'org.springframework.data', name: 'spring-data-rest-hal-browser', version: '3.0.8.RELEASE'

4. Creazione di una semplice API REST

4.1. Modello di dati semplice

Nel nostro esempio, configureremo una semplice API REST per sfogliare diversi libri nella nostra libreria.

Qui, definiamo una semplice entità libro che contiene le annotazioni appropriate in modo che possiamo persistere i dati 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. Presentazione di un repository CRUD

Successivamente, avremo bisogno di alcuni endpoint. Per fare ciò, possiamo sfruttare il PagingAndSortingRepository e specificare che vogliamo ottenere dati dalla nostra entità Book .

Questa classe fornisce semplici comandi CRUD, oltre a funzionalità di paging e ordinamento immediatamente disponibili:

@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); }

Se questo sembra un po 'strano, o se desideri saperne di più su Spring Repositories, puoi leggere di più qui.

Abbiamo esteso il repository aggiungendo due nuovi endpoint:

  • findByTitleContain: restituisce i libri che contengono la query inclusa nel titolo
  • findByAuthorContain: restituisce i libri dal database in cui l'autore di un libro contiene la query

Nota che il nostro secondo endpoint contiene l' attributo export = false . Questo attributo interrompe la generazione dei collegamenti HAL per questo endpoint e non sarà disponibile tramite il browser HAL.

Infine, caricheremo i nostri dati all'avvio di Spring definendo una classe che implementa l' interfaccia ApplicationRunner . Puoi trovare il codice su GitHub.

5. Installazione del browser HAL

La configurazione per il browser HAL è straordinariamente semplice quando si crea un'API REST con Spring. Finché abbiamo la dipendenza, Spring configurerà automaticamente il browser e lo renderà disponibile tramite l'endpoint predefinito.

Tutto quello che dobbiamo fare ora è premere run e passare al browser. Il browser HAL sarà quindi disponibile su // localhost: 8080 /

6. Esplorazione della nostra API REST con il browser HAL

Il browser HAL è suddiviso in due parti: l'esploratore e l'ispettore . Analizzeremo ed esploreremo ogni sezione separatamente.

6.1. L'HAL Explorer

A quanto pare, l'esploratore è dedicato all'esplorazione di nuove parti della nostra API rispetto all'endpoint corrente . Contiene una barra di ricerca e caselle di testo per visualizzare le intestazioni delle richieste personalizzate e le proprietà dell'endpoint corrente.

Di seguito, abbiamo la sezione dei collegamenti e un elenco cliccabile di risorse incorporate.

6.2. Utilizzo dei collegamenti

Se navighiamo al nostro endpoint / books possiamo visualizzare i collegamenti esistenti:

Questi collegamenti vengono generati dall'HAL nella sezione adiacente:

"_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.

Abbiamo creato una semplice API REST con Spring che implementa PagingAndSortingRepository , oltre a definire i nostri endpoint. Abbiamo anche visto come escludere determinati endpoint dal browser HAL .

Dopo aver definito la nostra API, l'abbiamo popolata con i dati di test e l'abbiamo esplorata in dettaglio con l'aiuto del browser HAL. Abbiamo visto come è strutturato il browser HAL e i controlli dell'interfaccia utente che ci hanno permesso di passare attraverso l'API ed esplorare i suoi dati.

Come sempre, il codice è disponibile su GitHub.

REST fondo

Ho appena annunciato il nuovo corso Learn Spring , incentrato sui fondamenti di Spring 5 e Spring Boot 2:

>> SCOPRI IL CORSO