Utiliser Insomnia pour les requêtes API

Introduction

Certains trouvent que les instructions curl et la ligne de commande, utilisées pour de nombreux exemples dans notre documentation sur les API de plate-forme, sont difficiles et intimidantes. Pour ceux-ci, il existe de nombreux outils pour envoyer des requêtes HTTP aux services basés sur REST, qui incluent la plupart des API Brightcove. Ce document vous montrera comment utiliser un outil populaire, l' Insomnia application.

Installer Insomnia

Sortez Insomnia de https://insomnia.rest . Insomnia peut être installé sur les systèmes Mac, Linux ou Windows.

Authentification

Insomnia peut être utilisé pour effectuer des requêtes à l'une des API RESTful de Brightcove. La plupart des API utilisent OAuth2 pour l'authentification, et nous verrons comment le configurer Insomnia plus loin dans ce document. Cependant, vous pouvez également l'utiliser pour les API qui n'utilisent pas OAuth, en définissant simplement l'en-tête approprié.

Voici à quoi ressemblera cet en-tête pour les requêtes avec des méthodes d'authentification autres que Oauth2 :

Playback API

  BCOV-Policy: YOUR_POLICY_KEY

Live API

  X-API-KEY: YOUR_API_KEY

API Zencoder

  Zencoder-Api-Key: YOUR_API_KEY

Obtenir les informations d'identification du client

Pour travailler avec la plupart des API Brightcove, vous aurez besoin des informations d'identification client pour le compte et les API que vous souhaitez utiliser. Obtenez vos informations d'identification client dans Studio en suivant les instructions dans Gestion des informations d'authentification API. Dans les étapes ci-dessous, nous ferons des CMS API demandes à l'aide Insomnia , de sorte que vos informations d'identification doivent avoir au moins les autorisations suivantes :

• Vidéos: Lire écrire

Vous pouvez ajouter autant d'autorisations supplémentaires que vous le souhaitez pour obtenir des informations d'identification qui seront utilisables pour un plus large éventail de demandes d'API. Notez également que vous pouvez obtenir des informations d'identification qui fonctionneront pour plusieurs comptes si vous le souhaitez.

Utilisation de Insomnia

Une fois que vous avez vos informations d'identification client, vous êtes prêt à commencer à utiliser Insomnia . Insomnia fera beaucoup de travail de configuration pour vous si vous importez la spécification OpenAPI pour l'API CMS, que nous mettons à votre disposition. Les étapes ci-dessous vous guident à travers la création de certains API CMS requêtes utilisant Insomnia.

Configuration d'une Insomnia collection pour l'API CMS

Obtenez la spécification OpenAPI pour l'API CMS

1. Ouvrez le Référence de l'API CMS.
2. Clique le Télécharger bouton et enregistrez le openapi.yaml déposer dans un endroit où vous pourrez le retrouver :

   

Importer la spécification OpenAPI dans Insomnia

1. Lancez l' Insomnia application.
2. Cliquez sur la liste déroulante à côté Insomnia et sélectionnez Importer/Exporter:

   

3. Dans la boîte de dialogue qui s'ouvre, cliquez sur Importer des données et sélectionnez À partir du fichier:

   

4. Sélectionnez le openapi.yaml fichier que vous avez téléchargé, puis choisissez d'importer les données dans l'espace de travail actuel ou d'en créer un nouveau. L'un ou l'autre fonctionnera, mais nous vous recommandons de créer un nouvel espace de travail pour chaque API :

   

5. Ensuite, il vous sera demandé si vous souhaitez importer les données en tant que collection de demandes ou document de conception. Choisir Demander la collecte:

   

6. Vous verrez une boîte de dialogue confirmant que les données ont été importées.
7. Cliquer sur Tableau de bord dans le coin supérieur gauche pour voir vos espaces de travail. Si vous avez créé un nouvel espace de travail, vous le verrez s'afficher avec le nom approprié :

   

8. Cliquez sur l'espace de travail pour l'ouvrir.
9. Vous verrez une liste de dossiers contenant les différents groupes de requêtes pour l'API CMS, ainsi qu'un nouvel environnement OpenAPI :

   

Ajouter des variables à l'environnement

Il s'agit d'une étape facultative, mais elle simplifiera la configuration de l'authentification pour les demandes ultérieurement.

1. Clique sur le Environnement OpenAPI menu déroulant et sélectionnez Gérer les environnements:

   

2. Vous verrez les variables d'environnement Insomnia créées à partir de la spécification OpenAPI sous la forme de JSON :

   

3. Ajoutez ces variables supplémentaires au JSON (voir Obtenir les informations d'identification du client ci-dessus sur client_id et client_secret) :
   • "account_id": "your_account_id"
   • "client_id": "your_client_id"
   • "client_secret": "your_client_secret"
   • "access_token_url": "https://oauth.brightcove.com/v4/access_token"
4. Lorsque vous avez terminé, l'environnement JSON devrait ressembler à ceci :

   

5. Cliquez sur Terminé dans le coin inférieur droit pour quitter la boîte de dialogue.

Configurer l'authentification

Nous sommes maintenant prêts à configurer l'authentification pour les requêtes API.

1. Clique le Vidéos dossier et sélectionnez le Obtenir des vidéos:

   

2. Notez que l'URL de la requête contient déjà deux variables. Si vous cliquez dessus, vous pouvez voir (et modifier) leurs valeurs. base_url est automatiquement généré par Insomnia à partir de la spécification OpenAPI. Si vous cliquez sur account_id, vous devriez constater que la valeur correspond à celle que vous avez saisie en tant que variable d'environnement dans la section précédente.
3. Clique le Authentification onglet et le Liste déroulante Authentification menu et sélectionnez OAuth 2.0:

   

4. Clique le Type de subvention liste déroulante et sélectionnez Identifiants du client:

   

5. Dans le URL du jeton d'accès champ, commencez à taper "access_token_url" - vous verrez le menu de saisie semi-automatique et sélectionnez votre access_token_url variables d'environnement :

   

6. Répétez l'étape précédente pour remplir le identité du client et Clé secrète du client champs avec votre client_id et client_secret variables :

   

7. Faites défiler vers le bas pour voir le Récupérer le jeton bouton et cliquez dessus. Assurez-vous que le champ Access Token est renseigné avec un jeton :

   

8. Cliquez sur Récupérer des jetons pour s'assurer que cela fonctionne. Vous devriez voir une réponse comme celle-ci :

   

9. Allez au Entête onglet et supprimez le Autorisation header (l'authentification que vous venez de mettre en place s'occupera de la tête - celle-ci la cassera):

   

Faire une demande

Nous sommes maintenant prêts à faire un Obtenir des vidéos demander.

1. Comme il s'agit d'une GET demande, il vous suffit de cliquer sur Envoyer.
2. Vous devriez voir la réponse JSON apparaître dans la zone Réponse :

   

3. Notez que vous pouvez récupérer différents ensembles de vidéos en utilisant Mettre en doute paramètres. Clique le Mettre en doute onglet pour la demande, et vous verrez que Insomnie l'a rempli sur la base de la spécification OpenAPI. Vérifiez simplement le(s) paramètre(s) que vous souhaitez utiliser et définissez les valeurs :

   

Envoyer un POST demander

Maintenant, nous allons envoyer un POST demande avec quelques données. Dans ce cas, nous allons créer un nouvel objet vidéo à l'aide de l'API CMS. Commencez par sélectionner le Créer une vidéo demande dans le Vidéos dossier.

1. Répétez toutes les étapes de la Configurer l'authentification section ci-dessus pour configurer l'authentification pour cette nouvelle demande.
2. Cette demande nécessite un corps de requête. Cliquez donc sur l'onglet JSON et entrez ce code JSON pour remplacer le null:

   {
   	"name": "Insomnia Test"
   }

   

3. Cliquez sur Envoyer et vous devriez voir le nouvel objet vidéo renvoyé dans la réponse.

Utilisation des générateurs de code

Une autre fonctionnalité intéressante de Insomnie est qu'il va générer du code pour faire des requêtes dans de nombreuses langues différentes.

1. Survolez le menu déroulant pour une demande :

   

2. Sélectionner Générer le code depuis le menu :

   

3. Dans le Générer le code client boîte de dialogue qui s'ouvre, choisissez la langue pour laquelle vous souhaitez coder :

   

4. Pour de nombreuses langues, vous pouvez également sélectionner des variantes qui peuvent être mieux adaptées au type d'application que vous créez :

   

5. Il existe également un bouton pratique pour copier le code dans votre presse-papiers :

   

Conclusion

Vous connaissez maintenant les bases de l'utilisation Insomnia pour effectuer des requêtes aux API Brightcove. Notez que si vous choisissez de mettre à niveau votre Insomnia compte gratuit vers un compte d'équipe, vous pouvez également synchroniser toutes vos demandes et environnements et les partager avec d'autres membres de l'équipe.