Spring REST und HAL Browser

REST Top

Ich habe gerade den neuen Learn Spring- Kurs angekündigt , der sich auf die Grundlagen von Spring 5 und Spring Boot 2 konzentriert:

>> Überprüfen Sie den Kurs

1. Übersicht

In diesem Tutorial werden wir diskutieren, was HAL ist und warum es nützlich ist, bevor wir den HAL-Browser einführen .

Wir werden dann Spring verwenden, um eine einfache REST-API mit einigen interessanten Endpunkten zu erstellen und unsere Datenbank mit einigen Testdaten zu füllen.

Schließlich werden wir mithilfe des HAL-Browsers unsere REST-API untersuchen und herausfinden, wie die darin enthaltenen Daten durchlaufen werden.

2. HAL und der HAL-Browser

JSON Hypertext Application Language (HAL) ist ein einfaches Format, das eine konsistente und einfache Möglichkeit bietet, Hyperlinks zwischen Ressourcen in unserer API zu erstellen . Die Aufnahme von HAL in unsere REST-API macht es für Benutzer viel erforschbarer und im Wesentlichen selbstdokumentierend.

Es funktioniert, indem Daten im JSON-Format zurückgegeben werden, die relevante Informationen über die API enthalten.

Das HAL-Modell dreht sich um zwei einfache Konzepte.

Ressourcen, die enthalten:

  • Links zu relevanten URIs
  • Eingebettete Ressourcen
  • Zustand

Links:

  • Eine Ziel-URI
  • Eine Beziehung oder rel zum Link
  • Einige andere optionale Eigenschaften, die bei der Abschreibung, Inhaltsverhandlung usw.

Der HAL-Browser wurde von derselben Person erstellt, die HAL entwickelt hat, und bietet eine In-Browser-GUI zum Durchlaufen Ihrer REST-API .

Wir werden jetzt eine einfache REST-API erstellen, den HAL-Browser anschließen und die Funktionen untersuchen.

3. Abhängigkeiten

Nachfolgend finden Sie die einzelne Abhängigkeit, die zum Integrieren des HAL-Browsers in unsere REST-API erforderlich ist. Den Rest der Abhängigkeiten für die API finden Sie im GitHub-Code.

Erstens die Abhängigkeit für Maven-basierte Projekte:

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

Wenn Sie mit Gradle erstellen , können Sie diese Zeile zu Ihrer build.gradle- Datei hinzufügen :

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

4. Erstellen einer einfachen REST-API

4.1. Einfaches Datenmodell

In unserem Beispiel richten wir eine einfache REST-API ein, um verschiedene Bücher in unserer Bibliothek zu durchsuchen.

Hier definieren wir eine einfache Buchentität, die entsprechende Anmerkungen enthält, damit wir die Daten im Ruhezustand beibehalten können:

@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. Einführung in ein CRUD-Repository

Als nächstes benötigen wir einige Endpunkte. Zu diesem Zweck können wir das PagingAndSortingRepository nutzen und angeben, dass wir Daten von unserer Book- Entität abrufen möchten .

Diese Klasse bietet einfache CRUD-Befehle sowie sofort einsatzbereite Paging- und Sortierfunktionen :

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

Wenn dies etwas seltsam aussieht oder Sie mehr über Spring Repositories erfahren möchten, können Sie hier mehr lesen.

Wir haben das Repository um zwei neue Endpunkte erweitert:

  • findByTitleContaining - Gibt Bücher zurück, die die im Titel enthaltene Abfrage enthalten
  • findByAuthorContaining - Gibt Bücher aus der Datenbank zurück, in der der Autor eines Buches die Abfrage enthält

Beachten Sie, dass unser zweiter Endpunkt das Attribut export = false enthält . Dieses Attribut verhindert, dass die HAL-Links für diesen Endpunkt generiert werden , und ist über den HAL-Browser nicht verfügbar.

Schließlich laden wir unsere Daten beim Start von Spring, indem wir eine Klasse definieren, die die ApplicationRunner- Schnittstelle implementiert . Sie finden den Code auf GitHub.

5. Installieren des HAL-Browsers

Das Setup für den HAL-Browser ist beim Erstellen einer REST-API mit Spring bemerkenswert einfach. Solange die Abhängigkeit besteht, konfiguriert Spring den Browser automatisch und stellt ihn über den Standardendpunkt zur Verfügung.

Jetzt müssen wir nur noch Run drücken und zum Browser wechseln. Der HAL-Browser ist dann unter // localhost: 8080 / verfügbar.

6. Erkunden unserer REST-API mit dem HAL-Browser

Der HAL-Browser ist in zwei Teile unterteilt - den Explorer und den Inspector . Wir werden jeden Abschnitt einzeln aufschlüsseln und untersuchen.

6.1. Der HAL Explorer

Wie es sich anhört, widmet sich der Explorer der Erkundung neuer Teile unserer API in Bezug auf den aktuellen Endpunkt . Es enthält eine Suchleiste sowie Textfelder zur Anzeige der benutzerdefinierten Anforderungsheader und -eigenschaften des aktuellen Endpunkts.

Darunter befindet sich der Abschnitt mit den Links und eine anklickbare Liste der eingebetteten Ressourcen.

6.2. Verwenden von Links

Wenn wir zu unserem Endpunkt / books navigieren, können wir die vorhandenen Links anzeigen:

Diese Links werden von der HAL im nebenstehenden Abschnitt generiert :

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

Wenn wir zum Suchendpunkt wechseln, können wir auch die benutzerdefinierten Endpunkte anzeigen, die wir mit dem PagingAndSortingRepository erstellt haben:

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

Die obige HAL zeigt unseren titelhaltigen Endpunkt mit geeigneten Suchkriterien. Beachten Sie, dass der vom Autor enthaltene Endpunkt fehlt, da wir definiert haben, dass er nicht exportiert werden soll.

6.3. Anzeigen eingebetteter Ressourcen

Eingebettete Ressourcen zeigen die Details der einzelnen Buchdatensätze auf unserem / books- Endpunkt an. Jede Ressource enthält auch einen eigenen Abschnitt mit Eigenschaften und Links :

6.4. Formulare verwenden

Die Fragezeichen-Schaltfläche in der Spalte GET im Abschnitt "Links" gibt an, dass ein Formularmodal zur Eingabe benutzerdefinierter Suchkriterien verwendet werden kann.

Hier ist das Formular für unseren titelhaltigen Endpunkt:

Unsere benutzerdefinierte URI gibt die erste Seite von 20 Büchern zurück, auf der der Titel das Wort "Java" enthält.

6.5. Der Hal-Inspektor

Der Inspektor bildet die rechte Seite des Browsers und enthält die Antwortheader und den Antworttext. Diese HAL-Daten werden zum Rendern der Links und eingebetteten Ressourcen verwendet , die wir zuvor im Lernprogramm gesehen haben.

7. Fazit

In diesem Artikel haben wir zusammengefasst, was HAL ist, warum es nützlich ist und warum es uns helfen kann, überlegene selbstdokumentierende REST-APIs zu erstellen .

Wir haben mit Spring eine einfache REST-API erstellt, die das PagingAndSortingRepository implementiert und unsere eigenen Endpunkte definiert. Wir haben auch gesehen, wie bestimmte Endpunkte vom HAL-Browser ausgeschlossen werden können .

Nachdem wir unsere API definiert hatten, füllten wir sie mit Testdaten und untersuchten sie mithilfe des HAL-Browsers im Detail. Wir haben gesehen, wie der HAL-Browser aufgebaut ist und welche UI-Steuerelemente es uns ermöglichten, die API zu durchlaufen und ihre Daten zu untersuchen.

Wie immer ist der Code auf GitHub verfügbar.

REST unten

Ich habe gerade den neuen Learn Spring- Kurs angekündigt , der sich auf die Grundlagen von Spring 5 und Spring Boot 2 konzentriert:

>> Überprüfen Sie den Kurs