Spring REST und HAL Browser

1. Überblick

In diesem Tutorial werden wirwhat HAL is and why it’s useful, before introducing the HAL browser diskutieren.

Anschließend verwenden wir Spring, 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 oder HAL ist ein einfaches Format, dasgives a consistent and easy way to hyperlink between resources in our API ist. Durch die Aufnahme von HAL in unsere REST-API wird es für Benutzer viel einfacher und im Wesentlichen selbstdokumentierend.

Es funktioniert, indem Daten im JSON-Format zurückgegeben werden, in denen relevante Informationen zur API aufgeführt sind.

DieHAL model revolves around two simple concepts.

Resources,, die enthalten:

Links zu relevanten URIs
Eingebettete Ressourcen
Zustand

Links:

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

Der HAL-Browser wurde von derselben Person erstellt, die HAL undprovides an in-browser GUI to traverse your REST API entwickelt hat.

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

3. Abhängigkeiten

Nachfolgend finden Sie die einzelnen Abhängigkeiten, die zur Integration des HAL-Browsers in unsere REST-API erforderlich sind. Den Rest der Abhängigkeiten für die API finden Sie inGitHub code.

Erstensthe dependency für Maven-basierte Projekte:


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

Wenn Sie mit Gradle erstellen, können Sie diese Zeile zu Ihrerbuild.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 mit Hibernate 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. Dazu können wirleverage the *PagingAndSortingRepository* and angeben, dass wir Daten von unsererBook -Sentität erhalten möchten.

Diese Klasseprovides simple CRUD commands, as well as paging and sorting capabilitiesist sofort einsatzbereit:

@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 mehrhere 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 unseresecond endpoint contains the export = false attribute. Dieses Attributstops the HAL links being generated for this endpointist nicht über den HAL-Browser verfügbar.

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

5. Installieren des HAL-Browsers

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

Alles, was wir jetzt tun müssen, ist die Taste "Ausführen" zu drücken und zum Browser zu wechseln. Der HAL-Browser ist dann aufhttp://localhost:8080/ verfügbar

6. Entdecken Sie unsere REST-API mit dem HAL-Browser

DieHAL browser is broken down into two parts – the explorer and the inspector. Wir werden jeden Abschnitt einzeln aufschlüsseln und untersuchen.

6.1. Der HAL Explorer

Wie es sich anhört, ist der Explorerexploring new parts of our API relative to the current endpoint gewidmet. Es enthält eine Suchleiste sowie Textfelder zur Anzeige vonCustom Request Headers and Properties des aktuellen Endpunkts.

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

6.2. Links verwenden

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

Dieselinks are generated from the HAL im nebenstehenden Abschnitt:

"_links": {
    "first": {
      "href": "http://localhost:8080/books?page=0&size=20"
    },
    "self": {
      "href": "http://localhost:8080/books{?page,size,sort}",
      "templated": true
    },
    "next": {
      "href": "http://localhost:8080/books?page=1&size=20"
    },
    "last": {
      "href": "http://localhost:8080/books?page=4&size=20"
    },
    "profile": {
      "href": "http://localhost:8080/profile/books"
    },
    "search": {
      "href": "http://localhost:8080/books/search"
    }
  },

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

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

Die obige HAL zeigt unseretitle-contains endpoint displaying suitable search criteria. Beachten Sie, wie der Endpunkt vonauthor-containsfehlt, da wir definiert haben, dass er nicht exportiert werden soll.

6.3. Anzeigen eingebetteter Ressourcen

Eingebettete Ressourcen zeigen diedetails of the individual book records auf unserem/books-Endpunkt. Jede Ressource enthält auch einen eigenen AbschnittProperties andLinks :

6.4. Formulare verwenden

Die Schaltfläche mit dem Fragezeichen in der Spalte GET im Abschnitt links gibt an, dass ein Formularmodal zum Eingeben benutzerdefinierter Suchkriterien verwendet werden kann.

Hier ist das Formular für unserentitle-contains endepunkt:

The HAL browser selection form

Unser individueller URI gibtfirst page of 20 books where the title contains the word ‘Java'. zurück.

6.5. Der Hal-Inspektor

Der Inspektor bildet die rechte Seite des Browsers und enthält dieResponse Headers and Response Body. ThisHAL data is used to render the Links and Embedded Resources , die wir zuvor im Tutorial gesehen haben.

7. Fazit

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

Wir haben mit Spring eine einfache REST-API erstellt, die diePagingAndSortingRepository implementiert und unsere eigenen Endpunkte definiert. Wir haben auch gesehen, wie manexclude certain endpoints from the HAL browser macht.

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

Wie immer ist der Codeover on GitHub. verfügbar

TOC

Spring REST und HAL Browser