Navigateur Spring REST et HAL

Haut REST

Je viens d'annoncer le nouveau cours Learn Spring , axé sur les principes de base de Spring 5 et Spring Boot 2:

>> VOIR LE COURS

1. Vue d'ensemble

Dans ce didacticiel, nous discuterons de ce qu'est HAL et de son utilité, avant de présenter le navigateur HAL .

Nous utiliserons ensuite Spring pour créer une API REST simple avec quelques points de terminaison intéressants et remplir notre base de données avec des données de test.

Enfin, à l'aide du navigateur HAL, nous explorerons notre API REST et découvrirons comment parcourir les données contenues dans.

2. HAL et le navigateur HAL

JSON Hypertext Application Language, ou HAL, est un format simple qui offre un moyen cohérent et facile de créer un lien hypertexte entre les ressources de notre API . L'inclusion de HAL dans notre API REST le rend beaucoup plus explorable pour les utilisateurs et est essentiellement auto-documenté.

Il fonctionne en renvoyant des données au format JSON qui présente des informations pertinentes sur l'API.

Le modèle HAL s'articule autour de deux concepts simples.

Ressources, qui contiennent:

  • Liens vers les URI pertinents
  • Ressources intégrées
  • Etat

Liens:

  • Un URI cible
  • Une relation, ou rel, au lien
  • Quelques autres propriétés facultatives pour aider à l'amortissement, à la négociation de contenu, etc.

Le navigateur HAL a été créé par la même personne qui a développé HAL et fournit une interface graphique intégrée au navigateur pour parcourir votre API REST .

Nous allons maintenant créer une API REST simple, connecter le navigateur HAL et explorer les fonctionnalités.

3. Dépendances

Vous trouverez ci-dessous la dépendance unique nécessaire pour intégrer le navigateur HAL dans notre API REST. Vous pouvez trouver le reste des dépendances de l'API dans le code GitHub.

Tout d'abord, la dépendance pour les projets basés sur Maven:

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

Si vous construisez avec Gradle, vous pouvez ajouter cette ligne à votre fichier build.gradle :

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

4. Construire une API REST simple

4.1. Modèle de données simple

Dans notre exemple, nous allons configurer une API REST simple pour parcourir différents livres de notre bibliothèque.

Ici, nous définissons une entité de livre simple qui contient les annotations appropriées afin que nous puissions conserver les données avec 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. Présentation d'un référentiel CRUD

Ensuite, nous aurons besoin de certains points de terminaison. Pour ce faire, nous pouvons exploiter le PagingAndSortingRepository et spécifier que nous voulons obtenir des données de notre entité Book .

Cette classe fournit des commandes CRUD simples, ainsi que des capacités de pagination et de tri dès la sortie de la boîte:

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

Si cela vous semble un peu étrange ou si vous souhaitez en savoir plus sur les référentiels Spring, vous pouvez en savoir plus ici.

Nous avons étendu le référentiel en ajoutant deux nouveaux points de terminaison:

  • findByTitleContaining - renvoie les livres qui contiennent la requête incluse dans le titre
  • findByAuthorContaining - renvoie les livres de la base de données où l'auteur d'un livre contient la requête

Notez que notre deuxième point de terminaison contient l' attribut export = false . Cet attribut arrête la génération des liens HAL pour ce point de terminaison et ne sera pas disponible via le navigateur HAL.

Enfin, nous chargerons nos données au démarrage de Spring en définissant une classe qui implémente l' interface ApplicationRunner . Vous pouvez trouver le code sur GitHub.

5. Installation du navigateur HAL

La configuration du navigateur HAL est remarquablement simple lors de la création d'une API REST avec Spring. Tant que nous avons la dépendance, Spring configurera automatiquement le navigateur et le rendra disponible via le point de terminaison par défaut.

Tout ce que nous avons à faire maintenant est d'appuyer sur Exécuter et de passer au navigateur. Le navigateur HAL sera alors disponible sur // localhost: 8080 /

6. Explorer notre API REST avec le navigateur HAL

Le navigateur HAL est divisé en deux parties: l'explorateur et l'inspecteur . Nous allons décomposer et explorer chaque section séparément.

6.1. L'explorateur HAL

Il semble que l'explorateur se consacre à l' exploration de nouvelles parties de notre API par rapport au point de terminaison actuel . Il contient une barre de recherche, ainsi que des zones de texte pour afficher les en- têtes de demande personnalisés et les propriétés du point de terminaison actuel.

En dessous, nous avons la section des liens et une liste cliquable de ressources intégrées.

6.2. Utilisation des liens

Si nous naviguons vers notre point de terminaison / books, nous pouvons afficher les liens existants:

Ces liens sont générés à partir du HAL dans la section adjacente:

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

Nous avons construit une API REST simple avec Spring qui implémente PagingAndSortingRepository , ainsi que la définition de nos propres points de terminaison. Nous avons également vu comment exclure certains points de terminaison du navigateur HAL .

Après avoir défini notre API, nous l'avons renseigné avec des données de test et l'avons exploré en détail à l'aide du navigateur HAL. Nous avons vu comment le navigateur HAL est structuré et les contrôles de l'interface utilisateur qui nous ont permis de parcourir l'API et d'explorer ses données.

Comme toujours, le code est disponible sur sur GitHub.

REST bas

Je viens d'annoncer le nouveau cours Learn Spring , axé sur les principes de base de Spring 5 et Spring Boot 2:

>> VOIR LE COURS