Navigateur Spring REST et HAL
1. Vue d'ensemble
Dans ce didacticiel, nous parlerons dewhat HAL is and why it’s useful, before introducing the HAL browser.
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 qu'elle contient.
2. HAL et le navigateur HAL
JSON Hypertext Application Language, ou HAL, est un format simple quegives a consistent and easy way to hyperlink between resources in our API. L'inclusion de HAL dans notre API REST le rend beaucoup plus explicite pour les utilisateurs, tout en étant essentiellement auto-documenté.
Cela fonctionne en renvoyant des données au format JSON qui décrit les informations pertinentes sur l'API.
LesHAL model revolves around two simple concepts.
Resources, qui contiennent:
-
Liens vers les adresses URI pertinentes
-
Ressources incorporé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 etprovides an in-browser GUI to traverse your REST API.
Nous allons maintenant créer une API REST simple, connecter le navigateur HAL et explorer les fonctionnalités.
3. Les 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 pour l'API dans lesGitHub code.
Premièrement,the dependency pour les projets basés sur Maven:
org.springframework.data
spring-data-rest-hal-browser
3.0.8.RELEASE
Si vous construisez avec Gradle, vous pouvez ajouter cette ligne à votrebuild.gradle file:
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 simple entité de livre contenant les annotations appropriées pour pouvoir 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 pouvonsleverage the *PagingAndSortingRepository* and spécifier que nous voulons obtenir des données de notreBook entity.
Cette classeprovides simple CRUD commands, as well as paging and sorting capabilitiesest prête à l'emploi:
@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 lire plus dehere.
Nous avons étendu le référentiel en ajoutant deux nouveaux points de terminaison:
-
findByTitleContaining – renvoie les livres contenant la requête incluse dans le titre
-
findByAuthorContaining – renvoie des livres de la base de données où l'auteur d'un livre contient la requête
Notez que nossecond endpoint contains the export = false attribute. Cet attributstops the HAL links being generated for this endpoint, 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'interfaceApplicationRunner. Vous pouvez trouver le code surGitHub.
5. Installation du navigateur HAL
La configuration du navigateur HAL est extrêmement 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.
Il ne nous reste plus qu'à appuyer sur Exécuter et basculer vers le navigateur. Le navigateur HAL sera alors disponible surhttp://localhost:8080/
6. Explorer notre API REST avec le navigateur HAL
LesHAL browser is broken down into two parts – the explorer and the inspector. Nous décomposerons et explorerons chaque section séparément.
6.1. L'explorateur HAL
En apparence, l'explorateur est consacré àexploring new parts of our API relative to the current endpoint. Il contient une barre de recherche, ainsi que des zones de texte pour afficher lesCustom Request Headers and Properties du point de terminaison actuel.
En dessous de celles-ci, nous avons la section des liens et une liste cliquable de ressources incorporées.
6.2. Utiliser des liens
Si nous naviguons vers notre point d'envoi/books , nous pouvons voir les liens existants:
Ceslinks are generated from the HAL dans la section adjacente:
"_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"
}
},Si nous passons au point de terminaison de recherche, nous pouvons également afficher les points de terminaison personnalisés que nous avons créés à l'aide desPagingAndSortingRepository:
{
"_links": {
"title-contains": {
"href": "http://localhost:8080/books/search/title-contains{?query,page,size,sort}",
"templated": true
},
"self": {
"href": "http://localhost:8080/books/search"
}
}
}Le HAL ci-dessus montre notretitle-contains endpoint displaying suitable search criteria. Notez comment le point de terminaisonauthor-contains est manquant car nous avons défini qu'il ne doit pas être exporté.
6.3. Affichage des ressources incorporées
Les ressources intégrées affichent lesdetails of the individual book records sur notre point de terminaison/books. Chaque ressource contient également sa propre sectionProperties andLinks :
6.4. Utiliser des formulaires
Le bouton de point d'interrogation dans la colonne GET de la section des liens indique qu'un formulaire modal peut être utilisé pour entrer des critères de recherche personnalisés.
Voici le formulaire pour notre point d'envoititle-contains :
Notre URI personnalisé renvoie lesfirst page of 20 books where the title contains the word ‘Java'.
6.5. L'inspecteur Hal
L'inspecteur constitue le côté droit du navigateur et contient leResponse Headers and Response Body. CeHAL data is used to render the Links and Embedded Resources t que nous avons vu plus tôt dans le didacticiel.
7. Conclusion
Dans cet article, nous avons résumé ce qu'est HAL, pourquoi il est utile et pourquoi il peut nous aider à créer dessuperior self-documenting REST APIs.
Nous avons construit une API REST simple avec Spring qui implémente lesPagingAndSortingRepository, ainsi que la définition de nos propres points de terminaison. Nous avons également vu commentexclude certain endpoints from the HAL browser.
Après avoir défini notre API, nous l'avons renseignée avec des données de test et l'exploré en détail à l'aide du navigateur HAL. Nous avons vu la structure du navigateur HAL et les contrôles de l'interface utilisateur qui nous ont permis de passer en revue l'API et d'explorer ses données.
Comme toujours, le code est disponibleover on GitHub.