Explorer les API de Planview AgilePlace avec Postman

Chaque utilisateur de Planview AgilePlace dispose d'une mine d'informations grâce à l'utilisation de l'interface de programmation d'applications (API) de Planview AgilePlace . L'API peut être utilisée pour extraire des informations d'état pour un rapport personnalisé, automatiser des tâches de routine telles que le déplacement ou la mise à jour d'une carte, synchroniser des données avec un autre système, et bien d'autres tâches utiles.

Toutefois, si vous n'avez jamais travaillé avec une API auparavant, le démarrage peut être un peu difficile. Heureusement, il existe d'excellents outils pour vous faciliter la tâche. Dans cet article, nous allons examiner l'un de mes outils API préférés, Postman.

Obtenir le facteur

Si vous avez Google Chrome, vous pouvez obtenir Postman sous la forme d'une extension Chrome . Si vous êtes sur un Mac, vous pouvez obtenir Postman sous forme d'application de bureau . Je m'attends à ce que Postman publie une application de bureau Windows à l'avenir.

Une fois installé, vous devriez voir l'écran de demande "Builder".

Effectuer votre première requête API

Pour votre première requête API, nous allons récupérer une liste de planches à partir de votre compte.

Saisissez l'URL et les informations d'identification de votre compte

Saisissez l'URL de la demande. Dans cet exemple, l'URL est https://demoarea.leankit.com/kanban/api/boards. Nous devrons remplacer demoarea par le nom de notre compte Planview AgilePlace.
Cliquez sur l'onglet Autorisation, s'il n'est pas déjà sélectionné.
Changez "No Auth" en "Basic Auth".
Saisissez l'adresse e-mail et le mot de passe de votre compte.
Cliquez sur le bouton "Mise à jour de la demande".

Mettez à jour les en-têtes de la demande

Cliquez sur l'onglet En-têtes.
Ajoutez deux en-têtes : Content-Type et Accept avec la valeur application/json.

La définition des en-têtes Content-Type et Accept permet à l'API de savoir que toutes les données que nous envoyons seront au format JavaScript Object Notation (JSON), et que toutes les données renvoyées doivent également être au format JSON.

Soumettre la demande

Nous sommes maintenant prêts à faire la demande ! Cliquez sur le bouton "Envoyer". Tant que l'URL et les informations de compte sont correctes, nous devrions voir quelque chose comme l'image suivante.

Une réponse de l'API sera presque toujours dans le format suivant :

Nous devrions maintenant avoir une liste de tableaux qui inclut l'Id , Title, Description, CreationDate (date de création du tableau), et d'autres informations de base.

Demander une planche unique

Maintenant que nous avons notre liste de cartes, nous pouvons utiliser l'Id d'une carte pour obtenir une seule carte avec tous ses détails, tels que les utilisateurs, les couloirs et les cartes.

À partir de la liste de planches de la requête précédente, copions l'Id d'une planche. Mettez à jour l'URL de la demande en ajoutant à la fin une barre oblique (/) et les Id du tableau que nous avons copié. Notre URL de requête devrait ressembler à quelque chose comme : https://myaccount.leankit.com/kanban/api/boards/1234.
Cliquez sur le bouton "Envoyer".

Réduire les blocs de données

Postman ne se contente pas de formater les données JSON pour les rendre plus lisibles, il permet de réduire facilement les sections de données afin que vous puissiez vous concentrer sur les informations qui vous intéressent. Pour réduire ou développer des blocs de données, cliquez sur la flèche à gauche.

Sauvegarder la demande

L'une des fonctionnalités intéressantes de Postman est la possibilité de sauvegarder les demandes, afin de pouvoir les réutiliser plus tard. Sauvegardons la demande pour le conseil afin de ne pas avoir à passer par toutes ces étapes précédentes à l'avenir.

Cliquez sur le bouton d'enregistrement.
Choisissez une collection ou créez une nouvelle collection. Une collection est comme un dossier pour stocker vos demandes. Nous pouvons créer une nouvelle collection en saisissant un nom sous "...ou en créer une nouvelle".
Saisissez un nom descriptif pour la demande.
Cliquez sur le bouton "Ajouter à la collection".

Recherche de cartes

Pour notre prochain tour, nous allons chercher sur les cartes.

Changez le type de demande de GET à POST.
Mettez à jour l'URL de la demande, en changeant myaccount pour correspondre à notre nom de compte, et 1234 pour correspondre à notre ID de conseil.
https://myaccount.leankit.com/kanban/api/board/1234/cartes de recherche
Note :/board/ dans cette URL est au singulier et non au pluriel, comme dans les demandes précédentes.
Cliquez sur l'onglet "Corps".
Sélectionnez le format de corps "brut".
Mettez à jour le corps avec le JSON suivant :
{ "searchOptions": { "Terme de recherche": "Ventes", "Page": 1 } }
Remarque : Changez le terme de recherche en tout texte qui correspondrait au titre ou à la description d'une carte de votre tableau. Une liste de toutes les options de recherche et de filtrage est disponible dans la documentation de Search Cards.
Cliquez sur "Envoyer" pour soumettre la demande.

Résultats de la recherche

Il est important de souligner que le JSON renvoyé par la recherche de cartes comprend les informations suivantes.

Propriété	Valeur
TotalResults	Le nombre total de cartes qui correspondent à la recherche.
Page	La "Page" actuelle ou les résultats.
MaxRésultats	Le nombre maximum de cartes retournées par la requête de recherche.

Si le nombre de cartes correspondant à votre recherche dépasse le MaxResults , vos résultats seront divisés en "Pages" qui nécessitent des requêtes séparées.

Par exemple, si notre recherche correspond à 33 cartes (" TotalResults": 33), seules les 20 premières cartes seront retournées. Pour obtenir les autres 13 cartes, nous devons modifier le corps de la requête comme suit, et soumettre à nouveau.