L'intégration des développeurs avec les collections d'API

Introduction

Dans ce billet, nous verrons comment une approche de la conception des API axée sur le produit avec des collections d'API créées à l'aide d'outils tels que Postman, Bruno ou Insomnia peut s'avérer très efficace en tant qu'artefacts d'intégration.

Ces collections sont des guides interactifs qui aident les développeurs à expérimenter des flux de travail en utilisant des données réelles, à réduire les frictions et à devenir plus rapidement productifs. Elles sont plus que des outils de création de requêtes.

Nous examinerons les raisons pour lesquelles les spécifications de l'OpenAPI, bien que précieuses, ont tendance à échouer dans la promotion de l'adoption réelle. Nous verrons également comment les collections peuvent communiquer l'histoire de votre API, rester cohérentes avec les bases de code versionnées et favoriser une culture de l'utilisabilité et de l'itération.

Conditions préalables

Pour suivre, vous aurez besoin de

• Un outil comme Postman, Bruno ou Insomnia (les exemples utilisent Postman)

• Accès aux clés API de Vonage ou à l'environnement de test

• Familiarité avec les concepts de base de l'API

Qu'est-ce qu'une collection d'API ?

Une collection d'API est un ensemble prédéfini de requêtes qui montrent comment utiliser une API de manière organisée et à l'aide d'exemples. Elles sont généralement utilisées dans des outils tels que Postman, Bruno ou Insomnia, mais vous pouvez également les créer à l'aide de scripts cURL structurés.

Ce qui rend les collections particulièrement puissantes, c'est leur interactivité. Au lieu de lire des informations sur un point de terminaison, les développeurs peuvent l'exécuter, modifier les paramètres et observer les réponses en temps réel.

Une collection d'API se compose de

• Définitions des requêtes (méthode, URL, en-têtes, corps)

• Variables d'environnement (par exemple, jetons d'authentification ou URL de base)

• Structures de dossiers représentant les flux de travail (par ex, Auth, Créer un utilisateur, Envoyer un message)

• Documentation en ligne

• Scripts de test pour la validation

Pourquoi l'intégration traditionnelle de l'API n'est pas à la hauteur

Les spécifications de l'API parlent, mais ne montrent pas

Les spécifications OpenAPI sont merveilleuses pour l'outillage, la validation et la documentation générée automatiquement. Mais il s'agit toujours de plans, et non de bâtiments. Elles définissent ce qui existe, mais pas quand ni comment l'utiliser. Elles n'ont pas de séquence, de narration ou de contexte.

La documentation ne peut pas prédire l'intention du développeur

Un développeur qui cherche simplement à "envoyer un SMS de test" risque de se perdre dans des plongées profondes sur les limites de taux ou les champs facultatifs dont il n'a pas encore besoin. En l'absence de bons exemples, les développeurs se contentent de deviner :

• Ai-je besoin de cet en-tête ?

• Dois-je encoder ce paramètre URL ?

• Pourquoi est-ce que je reçois un message 401 alors que mon jeton semble valide ?

Pas de terrain de jeu sûr

Les collections constituent un environnement structuré et modifiable dans lequel les développeurs ou les utilisateurs peuvent tester les flux de travail sans craindre de déclencher des comportements non souhaités.

Avantages des collections d'API

Les collections d'API améliorent l'expérience des développeurs de manière tangible, tant pour les publics internes qu'externes.

Fournir un démarrage rapide

Les collections API éliminent le problème de la page blanche. Plutôt que de partir de zéro, les développeurs ouvrent une collection et voient immédiatement :

• Demandes pré-remplies

• Gestion des variables d'authentification

• Structure claire pour les cas d'utilisation fréquents

Cela permet aux développeurs d'obtenir rapidement des résultats positifs et de créer une dynamique.

Permettre un apprentissage interactif

Les collections d'API favorisent l'exploration d'une manière qui n'est pas possible avec des documents statiques. Elles peuvent encourager un état d'esprit d'apprentissage par la pratique, par exemple :

• Que se passe-t-il si je modifie ce paramètre ?

• Puis-je combiner ces appels ?

• Comment fonctionne la gestion des erreurs ?

Activer le débogage

Les collections servent de langage commun à toutes les équipes :

• Les développeurs peuvent exporter les demandes qui échouent

• Les ingénieurs support peuvent rejouer et isoler les problèmes

• Les équipes d'assurance qualité peuvent valider les flux en phase d'essai

Permettre des tests sûrs et reproductibles

Grâce aux variables d'environnement, les collections facilitent les tests transversaux :

• Les structures de développement local

• API de mise en scène ou de bac à sable

• Environnements de production (avec précaution)

La collecte d'API peut être utilisée dans les tests automatisés ou pour valider les critères d'acceptation lors des revues de code.

Améliorer la communication entre les équipes

Les collections aident les différentes équipes à s'aligner sur le comportement de l'API. Elles constituent une documentation vivante qui évolue avec le produit.

Instaurer la confiance par la transparence

Les collectes montrent exactement ce qui est envoyé et reçu. Cette visibilité renforce la confiance, en particulier dans les entreprises et les environnements réglementés où la transparence est essentielle.

Comment créer et partager des collections d'API

Dans les sous-sections suivantes, vous trouverez une approche étape par étape pour créer une collection d'API efficace.

Commencer par un cas d'utilisation, pas par des points finaux

Ne vous contentez pas d'importer votre spécification OpenAPI dans Postman. Commencez par des flux de travail réels :

• Quelles sont les actions les plus courantes des développeurs ?

• Quel est le "Hello, World" de votre API ?

• À quoi ressemble un voyage complet ?

Par exemple :

• Créer un utilisateur test → Simuler un login → Générer un token

• Envoyer un SMS → Récupérer l'état du message

Utiliser un outil adapté à la pile technique du produit

Choisissez un outil qui correspond au flux de travail de votre équipe - Postman, Bruno, Insomnia, ou même VS Code REST Client.

Mise en place et configuration d'un nouveau projet de collection

Créez un projet/espace de travail et ajoutez :

1. Une nouvelle collection (par ex, API d'accueil des clients)

2. Dossiers pour les regroupements logiques (Auth, Utilisateurs, Paiements)

3. Requêtes avec :

   1. Noms descriptifs (Créer un utilisateur, Obtenir un jeton)Paramètres par défaut valides

   2. Brèves descriptions en ligne

Ajouter des variables d'environnement

Remplacer les valeurs codées en dur par des variables, par exemple : {{api_key}}, {{base_url}}, et {{access_token}}.

Créer des environnements pour :

• Développement local

• Mise en scène

• Production

Pour un usage interne, partagez les configurations de l'environnement via les espaces de travail.

Pour les utilisateurs externes, inclure des valeurs d'exemple et des instructions de configuration.

Facultatif : Ajoutez des scripts de pré-demande pour générer automatiquement des jetons pour les flux OAuth.

Inclure des exemples de réponses et de tests

Pour chaque demande :

• Ajouter des exemples de réponses réussies

• Inclure les réponses d'erreur courantes (401, 403, 500)

• Rédiger des scripts de test pour valider les réponses et extraire des valeurs (telles que des jetons ou des identifiants) qui peuvent être réutilisées dans des demandes ultérieures.

Gardez-le versionné

Traiter les collections comme du code :

• Stocker dans un repo GitHub

• Mise à jour lors des revues de sprint

• Version avec étiquettes ou branches alignées sur les notes de mise à jour

Partager dans les règles de l'art

Pour les clients externes

• Publier la collection via Public Workspaces ou GitHub

• Inclure un README avec des instructions d'installation

• Fournir un modèle d'environnement de base

Pour les équipes internes

• Stocker dans GitHub ou dans des espaces de travail partagés

• Épinglez à votre portail interne, à Notion ou aux documents d'accueil.

• Utilisez les robots Slack pour faire remonter des liens, par exemple "Need to test login ? Utilisez la collection Auth API → [lien]"

Exemple de l'API du centre de contact de Vonage avec Postman

Si vous souhaitez intégrer l'API de Vonage Contact Center, vous pouvez le faire en utilisant la collection officielle de Postman. Dans les étapes suivantes, je vous montrerai à quoi ressemble le flux d'accueil. Voici à quoi ressemble le flux d'accueil. Vous pouvez trouver la collection Postman officielle de Vonage pour en savoir plus.

Fourchette de la collection

Dans l'image ci-dessous, vous pouvez voir quels sont les dossiers de niveau racine de cette collection :

Root-Level API Folders in Postman Collection

Sur la page publique Postman, cliquez sur Fork.

Fork a Postman Collection for Vonage APIs

Créer/choisir un espace de travail (par exemple, customer-support-dev).

Create Postman workspace from Fork

Mise en place de l'environnement

Créer un nouvel environnement.

Root-Level API Folders in Postman CollectionAjoutez des variables telles que {{client_id}}, {{client_secret}} et {{region}} .

Vonage Auth Token Request from PostmanSélectionnez cet environnement dans la liste déroulante de Postman.

Select Environment in Postman

Authentifier

Exécuter la POST auth/connect/token demande.

Note : Postman remplira automatiquement les variables en utilisant les paramètres d'environnement des étapes précédentes.

Vonage User API GET Request from Postman

Effectuer un véritable appel à l'API

Exécuter GET /users à partir du dossier Utilisateurs.

Vonage Auth Endpoint Setup in PostmanFélicitations, vous êtes authentifié et prêt à tester le flux.

Vous pouvez aussi :

• Ajouter de nouveaux dossiers

• Modifier les paramètres

• Partagez avec votre équipe

• Version avec le code de l'application

Conclusion

Vous pourriez l'étendre avec des tests automatisés ou des intégrations CI, ou adapter la collection à d'autres API de Vonage comme Voice ou Messages.

Quand nous traitons API onboarding comme une expérience produit, collections d'API sont plus que pratiques, elles deviennent un compagnon stratégique. Une collection d'API créée avec soin peut :

• Simplifier la configuration initiale et la courbe d'apprentissage pour les nouveaux développeurs.

• Permettre aux développeurs de comprendre rapidement les API et de les utiliser efficacement.

• Guider les développeurs à travers les cas d'utilisation prévus et les capacités de l'écosystème API.

En intégrant la collecte d'API dans la documentation et les pratiques de contrôle de version, nous pouvons créer un environnement dans lequel l'apprentissage est interactif, le retour d'information est immédiat et l'adoption de l'API est possible. l'adoption de l'API est vraiment transparente.