Développement Développement L’API

Utilisation de Postman avec l’API Brightspace

Publié initialement le 20 février 2019

Notez que Postman est un outil de développement tiers. D2L vous recommande d’évaluer l’adéquation de Postman au sein de votre organisation avant de l’utiliser.

D2L et normes d’intégration

Chez D2L, nous avons et continuerons d’être de fervents partisans des normes d’intégration. À la fin de 2016, nous avons ajouté la prise en charge d’OAuth 2.0 pour le développement d’applications API Brightspace. OAuth 2.0 est un framework d’authentification standard ouvert qui fournit plusieurs flux d’authentification, y compris le flux OAuth à trois pattes. Il permet aux développeurs d’écrire des applications qui accèdent à différents services au nom d’un utilisateur.

Notez que nous continuerons à prendre en charge notre modèle d’authentification Id / Key Pair, mais notre objectif sera de continuer à prendre en charge et à stimuler la croissance d’OAuth 2.0. Un exemple de ceci est une mise à jour récente que nous avons faite de notre implémentation OAuth 2.0. Dans notre version de produit de mars 2019, nous avons ajouté la prise en charge de l’utilisation du paramètre Client_ID pour s’identifier lors de l’envoi de demandes au point de terminaison du jeton. Nous espérons que cette mise à jour sera bénéfique pour de nombreux développeurs de Brightspace.

Pourquoi avons-nous effectué cette mise à jour ?

L’inclusion de la valeur Client_ID n’aura pas d’impact sur les applications OAuth 2.0 existantes. En plus d’être plus conformes à la norme, par le biais de la communauté des développeurs, nous avons entendu de nos clients que notre implémentation OAuth 2.0 n’était pas compatible avec certains outils API tiers. Plus précisément, les développeurs de Brightspace n’ont pas pu utiliser Postman avec l’API Brightspace, car elle incluait la valeur Client_ID dans la demande d’interaction basée sur OAuth 2.0.

Qu’est-ce que Postman ?

Postman est l’outil de test d’API leader sur le marché. Il est disponible en téléchargement à l’adresse www.getpostman.com.

Postman est à la fois puissant et facile à utiliser et son Centre d’assistance est très utile. Parmi ses nombreuses fonctionnalités, nous pensons que les éléments suivants seront très utiles aux développeurs d’API Brightspace :

Créer des environnements de développement (par exemple, un pour votre site de test Brightspace et un pour votre site de production)
Créer des variables d’environnement (par exemple, domaine Brightspace, version de l’API)
Créer des collections qui permettent d’exécuter plusieurs appels d’API en séquence
Utiliser JavaScript pour transmettre des variables dans un appel API
Utiliser JavaScript pour stocker des variables après un appel d’API

Commencez avec une application Brightspace OAuth 2.0

L’utilisation de Postman avec Brightspace nécessite une application Brightspace OAuth 2.0. Si vous n’avez pas encore d’application OAuth 2.0, vous pouvez en créer une dans votre instance de Brightspace en accédant à Comment commencer avec OAuth 2.0, ou utilisez l’application publique fournie dans le Environnement de développement Brightspace (assurez-vous de rejoindre le groupe de développeurs pour accéder au fichier « Informations d’identification de l’instance de développeur », qui contient les détails de l’application publique OAuth 2.0).

Création d’une collection Postman et connexion à Brightspace

Avant de commencer, assurez-vous que vous avez installé Postman. Procédez comme suit pour configurer l’authentification Postman avec votre application Brightspace :

Lancez Postman.
Vous devriez être invité avec un Mise en route fenêtre. Sous la valeur par défaut Créer un nouveau, sélectionnez Collection.
Spécifiez un Nom pour votre nouvelle collection (p. ex. « Brightspace API Testing »).
Sélectionnez le Client Authorization onglet.
De l' Type déroulant, sélectionnez OAuth 2.0.
Pour l' Ajouter des données d’authentification à déroulant, sélectionnez En-têtes de demande.
Cliquez sur Obtenir un nouveau jeton d’accès.
L' Obtenir un nouveau jeton d’accès s’ouvre. Vous devrez configurer chaque champ comme suit :
- Fournir un Nom du jeton valeur (p. ex. « Brightspace Dev Environment Token »).
- Type de subvention défini sur Code d’autorisation.
- Définissez l’URL de rappel sur :
  
  https://oauth.pstmn.io/v1/browser-callback
  
  (selon le documentation de Postman sur OAuth 2.0)
- Définissez l’URL de l’enteur sur : https://auth.brightspace.com/oauth2/auth
- Définissez l’URL du jeton d’accès sur : https://auth.brightspace.com/core/connect/token
- Client ID doit correspondre à la valeur d’id client de votre application Brightspace.
- Client Secret doit correspondre à la valeur Client Secret de votre application Brightspace.
- Scope doit correspondre à la valeur Scope de votre application Brightspace.
- État peut être n’importe quelle valeur. Cette valeur est une fonctionnalité de sécurité destinée à protéger contre la falsification des demandes intersites. À des fins de test, cette valeur n’est pas très importante ; mais pour les applications de production, assurez-vous d’utiliser une valeur sécurisée sur le plan cryptographique.
- Le client Client Authorization défini sur Envoyer en tant qu’en-tête d’authentification de base.
- Cliquez sur Demander un jeton. Vous serez invité avec une fenêtre de connexion pour votre instance de Brightspace. Entrez dans le Nom d’utilisateur et Mot de passe de l’utilisateur que vous souhaitez effectuer des demandes d’API comme et cliquez sur S’identifier. En cas de succès, vous devriez voir une invite de consentement pour confirmer l’utilisation de l’application. Acceptez cette invite (notez que cette invite ne se produit que pour un utilisateur la première fois qu’il accède à l’application).
La fenêtre devrait se fermer et vous verrez un Jeton d’accès valeur entrée dans la collection. Faites défiler jusqu’au bas de la fenêtre et cliquez sur Utiliser le jeton.
Cliquez sur Créer pour créer votre collection.

Vous disposez désormais d’une collection Postman connectée à Brightspace à l’aide de OAuth 2.0. L’étape suivante consiste à ajouter une demande d’API à votre collection.

Ajout de demandes de Brightspace à votre collection Postman

L’un des aspects puissants de Postman est que vous pouvez ajouter une ou plusieurs demandes d’API à une collection.

Pour ajouter une demande à votre collection

Cliquez sur Nouveau.
Sélectionnez un Demande et entrez un Nom de la demande et Description de la demande.
Assurez-vous que votre collection est Sélectionnée comme emplacement de sauvegarde. Cliquez sur Enregistrer dans {votre collection}.

À ce stade, vous serez ramené à la page d’accueil de Postman, mais vous avez maintenant la possibilité d’ajouter une demande d’API spécifique. Vous pouvez fournir à Postman les détails de n’importe quel itinéraire d’API Brightspace que vous souhaitez tester à ce stade. Vous pouvez ajouter une demande pour OBTENIR une liste de tous les quiz qui existent dans un cours spécifique.

Pour le premier champ, spécifiez GET comme méthode HTTP.
Dans le champ URL de la demande, vous devez créer le point de terminaison d’API complet. Cela inclut l’URL de l’instance.
1. Commencez par l’URL de votre instance.
2. Entrez l’URL de l’API que vous souhaitez appeler (par exemple, /d2l/api/le/(version)/(orgUnitId)/quizzes/).
Substituez la valeur (version) par votre version actuelle de l’API.
Substituez votre orgUnitId par le cours à cibler.
Cliquez sur l’onglet Autorisation et assurez-vous Hériter de l’authentification du parent pour Type est défini.
Une fois les détails de la demande entrés et l’autorisation spécifique, cliquez sur Envoyer pour tester la nouvelle demande.
Vous devriez maintenant recevoir une réponse 200 avec une série de quiz actuellement disponibles pour votre utilisateur dans l’orgUnit spécifique.

S’il n’existe aucun quiz, vous pouvez vous attendre à une erreur 404 pour aucun quiz trouvé. Si votre utilisateur n’est pas autorisé à voir les quiz, vous recevrez une erreur 403 non autorisée.

Utilisations avancées de Postman

Postman contient des fonctionnalités supplémentaires qui permettent à la fois de gagner du temps et d’améliorer la compréhension d’un itinéraire API. Postman permet la collecte et / ou l’environnement variables. Celles-ci vous permettent de substituer des valeurs dans vos demandes pour ajouter rapidement de nouveaux points de terminaison ou tester dans différentes instances. Voici quelques idées pour vous aider à démarrer :

Créez une variable d’environnement qui définit l’URL de votre instance Brightspace
Créez une variable de version pour stocker la valeur fournie dans vos URL d’API

Une autre grande caractéristique est scripts. Postman contient un environnement d’exécution (basé sur Node.js) qui vous permet d’ajouter du code dynamique à vos demandes soit avant la demande soit juste après qu’un appel est effectué. Les utilisateurs peuvent ajouter des scripts de pré-demande et de post-demande à des dossiers de collections ou à des demandes spécifiques. Les scripts sont idéaux pour des situations telles que :

Interroger la version de l’API d’une instance et fournir la valeur dans une variable pour une demande ultérieure
Enregistrer la valeur d’un OrgUnitId et la transmettre pour une recherche dans une demande suivante
Effectuer une fonction de calcul avant de soumettre les données dans une API POST

Problèmes avec Postman et Brightspace

Notre évaluation de Postman a été prometteuse et positive. Cependant, nous avons rencontré quelques problèmes dont vous devriez être au courant.

Effacer les cookies : Au moment de la publication de cet article, nous avons remarqué qu’il n’y a pas de problèmes la première fois que des jetons OAuth sont générés. Cependant, les tentatives ultérieures ont des problèmes. Pour résoudre ce problème, nous recommandons à effacer les cookies au sein de Postman.

Absence de redirection de connexion : Lors de la génération d’un jeton OAuth, l’utilisateur est envoyé de Postman à la page de connexion de l’instance Brightspace avec laquelle il développe. Il n’y a pas d’options pour rediriger vers une autre page de connexion Brightspace dans le navigateur intégré de Postman. Cela pose un problème uniquement si le compte d’utilisateur que vous utilisez pour développer n’est pas enregistré auprès du fournisseur d’identité de votre page de connexion principale.

Nous évaluons ces deux problèmes. Cependant, nous pensons qu’il s’agit de problèmes spécifiques à Postman. Nous serions ouverts aux suggestions sur la façon de mieux contourner ces problèmes, et nous fournirons toutes les mises à jour que nous recevrons dans cet article.

Conclusion

Faites-nous part de votre expérience avec Postman et partagez avec nous toutes les collections Postman que vous développez. S’il y a un autre client de test d’API que vous préférez à Postman, nous aimerions le savoir afin que nous puissions également le tester.

Pour plus de formation sur l’utilisation de Postman, reportez-vous à la section Apprenez Postman avec Paul.

Figure : Affichez les détails d’une demande sur l’écran de demande.