Connecter et interroger une API REST ou GraphQL
Une API permet à votre site de demander des données à un autre service. Dans Communik, la connexion se configure dans Données, sous REST API. Les formulaires décrivent le service, la requête et la partie de la réponse à utiliser.
Vous allez préparer une connexion, tester sa requête, puis afficher les données reçues sur une page et vérifier le site de test. La démonstration utilise trois escapades fictives. Commencez par ce cas simple avant de construire une page complète.
1. Préparer les informations du service
Demandez au fournisseur l’adresse de base, le chemin de la requête, la méthode HTTP, un exemple de réponse et les accès nécessaires. L’adresse seule ne suffit pas à déterminer comment lire les données.
Dans Données, cliquez sur + à côté de REST API, donnez un nom à la connexion et créez-la. Si elle existe déjà, sélectionnez son nom dans le menu. Consultez aussi la différence entre collection et source externe.
2. Renseigner la connexion
Lecture impossible. Réessayez avec les commandes vidéo.
Dans General, renseignez URL de base avec l’adresse du service. Le nom vous aide à retrouver la connexion ; la description peut expliquer son rôle.
La vidéo utilise http://127.0.0.1:4377, une API locale réservée à la démonstration. Cette adresse ne fonctionnera pas sur votre site public. Utilisez l’adresse HTTPS fournie par votre service, accessible depuis le serveur du site.
Pour ce premier test, l’API de démonstration est publique et ne demande aucune authentification. Si votre service exige un accès, configurez-le dans Authentication avant de tester. Ne publiez jamais une clé dans un article, une image ou un texte de page.
3. Décrire la requête
Ouvrez Endpoints, puis Créer un point de terminaison. Un point de terminaison est une requête vers une partie du service.
- Donnez un nom parlant : Escapades Alma dans notre exemple.
- Gardez GET, la méthode prévue par cette API pour lire les données.
- Renseignez le chemin /escapades.
Communik utilise l’adresse de base et ce chemin pour appeler le service. Recopiez les informations de sa documentation. Changer la méthode ne transforme pas automatiquement une lecture en écriture autorisée.
4. Repérer les données de la réponse
Ouvrez l’onglet Réponse de la requête. Choisissez le mode liste lorsque vous recevez plusieurs éléments. Le chemin des données indique où se trouve cette liste dans la réponse.
Dans notre exemple, les escapades sont sous la clé data : saisissez data. Si votre service renvoie sa liste sous une autre clé, adaptez ce chemin à son exemple de réponse.
Enregistrez avec la commande Sauvegarder du builder, puis lancez Détection automatique. Dans la démonstration, Communik reçoit trois lignes et reconnaît leurs champs : id, titre et categorie. L’aperçu affiche un extrait, pas nécessairement toute la liste.
La correspondance des champs relie le nom utilisé par l’API au nom que vous souhaitez utiliser. Conservez d’abord les noms proposés. Vous pourrez les adapter après avoir validé la lecture.
5. Enregistrer et vérifier
Lecture impossible. Réessayez avec les commandes vidéo.
Sauvegardez après la détection. Rouvrez la connexion pour vérifier que l’adresse et la requête sont conservées.
Une réponse correcte prouve que cette requête peut lire ces données. Elle ne prouve pas encore que vos éléments de page sont reliés à la source. Vérifiez ensuite leur association et le résultat sur votre site de test.
Si la réponse est vide, le panneau affiche Aucune donnée. Cela peut être normal si aucun contenu ne correspond. Contrôlez aussi le chemin des données : une réponse reçue ne signifie pas que la bonne liste a été sélectionnée.
Si la requête échoue, le panneau affiche Erreur, le statut HTTP et le message disponible. Corrigez l’adresse, les accès ou le service selon ce message, puis utilisez Réessayer. Une erreur d’accès ne se corrige pas en recréant la collection CMS.
6. Fournir un accès au service
Lecture impossible. Réessayez avec les commandes vidéo.
Lecture impossible. Réessayez avec les commandes vidéo.
Dans Authentication, choisissez le type demandé par le fournisseur. La configuration décrit la méthode d’accès ; l’onglet Credentials reçoit les identifiants correspondants.
Pour le test GraphQL, choisissez Bearer Token, puis renseignez le jeton dans Credentials et utilisez Enregistrer les informations d’identification. Cette sauvegarde est distincte de celle des réglages de la connexion. Le formulaire vide ensuite le champ : cela ne signifie pas que le jeton est perdu.
La démonstration utilise un jeton fictif, alma-demo-only. Il ne donne accès à aucun service client. Remplacez-le par votre propre accès lorsque vous configurez votre service et gardez ce panneau hors de vos captures partagées.
Choisissez selon les indications du fournisseur :
| Méthode | Informations à saisir | Portée vérifiée |
|---|---|---|
| Bearer Token | Le jeton dans Credentials | Requête GraphQL avec un jeton fictif |
| Basic | Le nom d’utilisateur et le mot de passe dans Credentials | Lecture REST acceptée par le service |
| API Key | Le nom de l’en-tête dans Authentication, puis la clé dans Credentials | En-tête simple, préfixe et paramètre d’URL |
| Custom Headers | Les noms et les valeurs des en-têtes dans Credentials | Accès reçu dans le builder et le moteur du site |
| OAuth 2.0 | Un Access Token déjà obtenu, dans Credentials | Lecture avec ce jeton ; échange et renouvellement automatiques non validés |
La vidéo Basic utilise un compte fictif réservé à la démonstration. Après l’enregistrement des accès, elle teste la vraie requête et reçoit trois lignes. Suivez le même principe avec votre service : enregistrer des accès ne suffit pas à prouver que la requête est autorisée.
Pour une API Key, choisissez l’envoi dans un en-tête ou un paramètre d’URL, puis indiquez le nom demandé par le fournisseur. Si un préfixe est requis, renseignez-le dans le réglage prévu. Ces variantes et deux en-têtes personnalisés ont été contrôlés après sauvegarde dans le builder et dans le moteur du site, avec des accès fictifs.
7. Lire des données avec GraphQL
GraphQL est une autre manière d’interroger un service. Votre fournisseur doit vous donner son adresse et une requête adaptée à son schéma. Une requête prise sur un autre service peut être invalide, même si les deux utilisent GraphQL.
Dans notre exemple :
- Créez un point de terminaison Escapades GraphQL.
- Choisissez POST et le chemin /graphql.
- Dans le modèle du corps, recopiez la requête fournie.
- Dans Réponse, gardez une liste et indiquez le chemin data.escapades.
- Sauvegardez, puis lancez Détection automatique.
La requête de démonstration demande deux escapades. Le panneau reçoit deux lignes depuis un moteur GraphQL et leur accès est protégé par le jeton fictif enregistré précédemment.
Le second onglet Paramètres sert à déclarer les valeurs variables d’une requête. Son nom peut être confondu avec le premier onglet, qui contient la méthode et le chemin : vérifiez le contenu du panneau avant de saisir une valeur.
Vous pouvez aussi déclarer un paramètre dans l’onglet Paramètres de la requête, avec son nom, son type et sa valeur Défaut. Si l’exécution ne fournit pas de valeur, cette valeur par défaut est utilisée. Par exemple, un paramètre numérique limite avec un défaut de 2 demande deux résultats ; une valeur explicite de 1 prend le dessus. Une valeur de 0 reste bien zéro.
Si le service répond avec une erreur GraphQL, le panneau affiche Erreur avec le message du service. Une liste valide sans résultat affiche Aucune donnée. Vérifiez la requête et les paramètres avant de réessayer.
Modèle de requête utilisé dans la démonstration
{"query":"{ escapades(limite: 2) { id titre categorie } }"}
Ce modèle est propre au schéma de la démonstration. Le jeton reste dans Credentials ; il n’est pas ajouté au corps de la requête. Le test utilise un moteur GraphQL qui interprète la requête et ses variables.
Pour les agences : GraphQL, paramètres et portée du test
Un service GraphQL exige généralement une requête POST et un corps contenant la requête GraphQL, selon les règles du fournisseur. Le formulaire REST permet de choisir POST et de renseigner un modèle de corps. Un endpoint REST GET ne constitue pas une validation GraphQL.
Cette première démonstration vérifie une lecture GET sans authentification, trois données réelles, la sauvegarde et le rechargement. Une seconde démonstration contrôle GraphQL en POST, un jeton Bearer fictif, une requête simple à deux résultats ; les paramètres numériques avec défaut, remplacement explicite et valeur zéro ont aussi été contrôlés après sauvegarde dans le builder, ainsi qu’une erreur GraphQL visible. Basic, clé API simple en en-tête, en-têtes personnalisés et OAuth avec un jeton explicitement fourni ont été comparés sur une API HTTP. L’association au champ titre est également contrôlée après publication et republication sur le site de test, sur ordinateur et mobile. La pagination distante et l’écriture ne sont pas couvertes par ce guide de lecture. La connexion ne crée pas de fiches CMS et ne garantit pas une synchronisation dans les deux sens.
8. Associer la requête à un élément de page
Lecture impossible. Réessayez avec les commandes vidéo.
La connexion dans Données sert à préparer le service. Pour choisir où utiliser ses résultats, ouvrez votre page, passez en Expert et sélectionnez l’élément concerné. Dans Listes & Données, ajoutez API externe, choisissez la connexion et la requête, puis utilisez Appliquer et actualiser. Ces commandes restent visuelles : le mode Expert ne nécessite pas de classes CSS.
Dans le contenu du texte, saisissez @ puis choisissez le champ reçu par l’API, par exemple titre. Sauvegardez et rechargez la page pour vérifier que la donnée remplace le texte fixe. Ce choix de champ est désormais opérationnel dans le builder.
Vérifiez ensuite le résultat sur votre site de test, sur ordinateur et mobile. Le texte doit afficher la donnée reçue, comme dans le builder. Après une modification de la requête, sauvegardez, republiez et contrôlez de nouveau la page.
Comme la requête renvoie une liste, l’élément associé se répète pour ses trois résultats. Dans notre démonstration, le premier titre est Une pause face à l’océan. Deux requêtes différentes ont été publiées successivement et vérifiées sur le même serveur, sans redémarrage entre les publications. Le résultat reste visible après publication sur ordinateur et mobile.
Si le texte manque, commencez par vérifier la réponse de la requête, le chemin des données et le champ sélectionné. Assurez-vous d’avoir sauvegardé les réglages puis publié la version que vous consultez. Une donnée présente dans l’aperçu du builder doit aussi être contrôlée sur le site de test.
Une API externe fournit des données à la page ; cette association ne crée pas automatiquement des fiches dans vos collections. Pour les données stockées dans le CMS Communik, utilisez le guide des listes CMS.