Jira, plateforme polyvalente de suivi des tickets et de gestion de projets d'Atlassian, est devenue un outil indispensable pour d'innombrables équipes de développement dans le monde entier. Si son interface conviviale facilite la gestion des projets et le suivi des tickets, la véritable puissance de Jira réside dans ses nombreuses options de personnalisation et ses capacités d'intégration. Au cœur de ces possibilités se trouve l'API REST Jira, qui ouvre la voie à l'automatisation des tâches, à la création d'applications personnalisées et à l'intégration fluide de Jira avec les autres outils de votre écosystème de développement. Dans ce guide complet, nous allons explorer en détail l'API REST Jira, ses fonctionnalités et des exemples pratiques pour vous aider à démarrer.
À retenir : L'API REST Jira est un outil polyvalent permettant d'automatiser des tâches, de créer des applications personnalisées et d'intégrer Jira à d'autres outils de développement, aussi bien dans les versions Cloud que Server/Data Center. Elle offre un large éventail de fonctionnalités, notamment la gestion des tickets, les opérations en masse et les rapports personnalisés, avec la prise en charge de fonctions avancées telles que la pagination et l'expansion des données. Malgré certaines différences entre les versions, les fonctionnalités essentielles de l'API restent cohérentes, ce qui permet aux équipes de personnaliser efficacement Jira selon leurs besoins et de l'intégrer de manière fluide à leur écosystème de développement.
Vous pouvez essayer Jira sans utiliser d'API sur Latenode
Qu'est-ce que l'API Jira ?
À la base, une API (Application Programming Interface, ou interface de programmation d'applications) est un ensemble de protocoles et d'outils qui définissent la manière dont les composants logiciels doivent interagir. Dans le contexte de Jira, l'API permet à des applications externes d'interagir avec Jira par programmation, notamment pour récupérer et manipuler des données et exécuter des actions dans Jira. Jira propose deux types d'API :
Qu'est-ce que l'API Java ?
L'API Java Jira est un outil puissant pour les développeurs qui créent des applications ou des plugins Jira personnalisés. Elle fournit un accès direct aux objets et méthodes Java sous-jacents du serveur Jira, permettant une intégration et une personnalisation approfondies. Toutefois, ce niveau d'accès est disponible uniquement pour les installations Jira sur site (Server ou Data Center), où vous disposez d'un accès direct au serveur. Si vous utilisez Jira Cloud ou créez une intégration autonome, l'API REST est le choix à privilégier.
Qu'est-ce que l'API REST ?
REST (Representational State Transfer) est un style architectural qui définit un ensemble de contraintes pour créer des services web. Une API REST expose un ensemble de endpoints HTTP auxquels il est possible d'accéder en envoyant des requêtes avec des méthodes HTTP spécifiques (GET, POST, PUT, DELETE) afin d'effectuer des opérations sur des ressources.
L'API REST Jira suit cette architecture et fournit un ensemble complet d'endpoints permettant d'interagir avec presque tous les aspects de Jira, des tickets et projets aux tableaux agiles et tableaux de bord. Elle renvoie les données au format JSON et prend en charge différentes méthodes d'authentification afin de garantir un accès sécurisé.
L'un des principaux avantages de l'API REST est son indépendance vis-à-vis des plateformes : vous pouvez appeler l'API depuis tout appareil ou application capable d'effectuer des requêtes HTTP, quel que soit le langage de programmation utilisé. C'est donc le choix idéal pour créer des intégrations entre Jira et d'autres outils, ou pour automatiser les interactions avec Jira depuis la ligne de commande.
Que pouvez-vous faire avec l'API REST Jira ?
Les possibilités sont presque infinies. Voici seulement quelques exemples de ce que vous pouvez accomplir avec l'API REST Jira :
- Automatiser la création de tickets : intégrez Jira à votre système de suivi des erreurs ou à votre outil de support client afin de créer automatiquement des tickets Jira lorsqu'un événement spécifique se produit, avec tous les détails pertinents.
- Synchroniser les données entre les systèmes : maintenez Jira synchronisé avec les autres outils de votre chaîne de développement, tels que les systèmes de gestion du code source, les outils CI/CD ou les suites de gestion des tests. L'API vous permet de répercuter les modifications de Jira vers d'autres systèmes, et inversement.
- Opérations en masse : vous devez mettre à jour un grand nombre de tickets simultanément ? L'API REST prend en charge les opérations de création, de mise à jour et de suppression en masse, ce qui vous fait gagner d'innombrables heures de travail manuel.
- Tableaux de bord et rapports personnalisés : récupérez les données de Jira et utilisez-les pour créer des tableaux de bord, rapports ou visualisations de données personnalisés, adaptés aux besoins spécifiques de votre équipe.
- Étendre les fonctionnalités de Jira : créez des applications et intégrations personnalisées qui étendent les capacités de Jira, ajoutent de nouvelles fonctions ou simplifient les workflows propres à votre organisation.
- Migrer des données : vous passez d'un autre système de suivi des tickets à Jira ? Utilisez l'API pour importer vos données existantes dans Jira par programmation.
- Sauvegarder et archiver : configurez des scripts pour sauvegarder régulièrement vos données Jira ou archiver les anciens projets et tickets.
Ce ne sont que quelques exemples : l'API REST Jira fournit un vaste ensemble d'endpoints couvrant presque toutes les fonctionnalités accessibles via l'interface utilisateur de Jira. Si vous pouvez le faire dans Jira, il y a de fortes chances que vous puissiez aussi le faire via l'API.
Principales différences entre l'API REST Jira Cloud et l'API REST Data Center
Bien que l'API REST Jira offre globalement les mêmes capacités dans Jira Cloud, Server et Data Center, il existe quelques différences importantes à connaître :
- Authentification : Jira Cloud utilise OAuth 2.0 ou des tokens API pour l'authentification, offrant une méthode sécurisée et fondée sur des standards pour accorder l'accès à l'API. Jira Data Center, quant à lui, utilise principalement l'authentification basique ou des cookies de session.
- Versionnement de l'API : l'API REST Jira Cloud est versionnée (actuellement en version 3), ce qui permet à Atlassian de faire évoluer et d'améliorer l'API au fil du temps sans interrompre les intégrations existantes. Jira Data Center, en revanche, n'a pas de versionnement explicite : l'API est liée à la version spécifique de Jira.
- Limitation du débit : afin de garantir une utilisation équitable et de maintenir les performances, Jira Cloud applique des limites de débit plus strictes aux requêtes API que Data Center. Les intégrations doivent être conçues en tenant compte de ces limites, avec une régulation et une gestion des erreurs appropriées.
- Format des URL : les URL des endpoints de l'API REST diffèrent légèrement entre Cloud et Data Center. Pour Jira Cloud, l'URL de base se présente sous le format https://your-domain.atlassian.net/rest/api/3/, tandis que pour Data Center, elle est https://your-jira-instance.com/rest/api/latest/.
Malgré ces différences, les concepts fondamentaux et les modèles d'utilisation de l'API REST restent largement identiques entre les différents déploiements. Les compétences et connaissances acquises avec une version de l'API seront facilement transférables aux autres.
De quoi avez-vous besoin pour utiliser l'API REST Jira ?
Pour commencer avec l'API REST Jira, vous aurez besoin des éléments suivants :
- Une instance Jira : il peut s'agir d'un site Jira Cloud ou d'une instance Jira Server ou Data Center auto-hébergée. Vous aurez besoin d'un accès administrateur pour configurer et gérer vos intégrations API.
- Identifiants d'authentification : selon votre déploiement Jira, il peut s'agir d'un token OAuth 2.0, d'un token API ou d'identifiants d'authentification basique (nom d'utilisateur et mot de passe).
- Client API : pour effectuer des requêtes HTTP vers l'API, vous aurez besoin d'un client API. Il peut s'agir d'un outil de test d'API dédié comme Postman, d'un outil en ligne de commande comme cURL ou de la bibliothèque HTTP du langage de programmation de votre choix (par exemple, la bibliothèque requests de Python ou l'API fetch de JavaScript).
- Documentation de référence de l'API Jira : Atlassian fournit une documentation complète pour l'API REST Jira, détaillant chaque endpoint, ses paramètres ainsi que des exemples de requêtes et de réponses. Gardez-la à portée de main lorsque vous explorez l'API.
Une fois ces éléments en place, vous êtes prêt à effectuer vos premières requêtes API.
Comment utiliser l'API REST Jira
Voyons un exemple pratique d'utilisation de l'API REST Jira pour créer, récupérer, mettre à jour et rechercher des tickets. Nous utiliserons Postman dans nos exemples, mais les principes s'appliquent à n'importe quel client API.
Étape 1 : créer un compte Jira Cloud
Si vous n'avez pas encore d'instance Jira sur laquelle travailler, le moyen le plus simple de commencer consiste à vous inscrire pour obtenir une instance Jira Cloud gratuite sur https://www.atlassian.com/software/jira. Une fois votre site configuré, créez un nouveau projet sur lequel travailler.
Étape 2 : générer un token API Jira
Pour authentifier nos requêtes API, nous utiliserons un token API. Voici comment en générer un :
- Connectez-vous à votre compte Atlassian et accédez à https://id.atlassian.com/manage-profile/security/api-tokens.
- Cliquez sur « Create API token », attribuez un libellé descriptif à votre token, puis cliquez sur « Create ».
- Copiez le token généré et stockez-le de manière sécurisée. Vous ne pourrez plus l'afficher après avoir quitté cette page.
Étape 3 : effectuer votre première requête API avec Postman
Commençons par récupérer les détails d'un ticket existant :
- Ouvrez Postman et créez une nouvelle requête.
- Définissez la méthode HTTP sur GET et saisissez l'URL de l'endpoint de détail du ticket, en remplaçant your-domain par le domaine de votre site Jira et ISSUE-KEY par la clé d'un ticket de votre projet : https://your-domain.atlassian.net/rest/api/3/issue/ISSUE-KEY
- Dans l'onglet « Authorization », sélectionnez « Basic Auth » comme type. Saisissez l'adresse e-mail de votre compte Atlassian comme nom d'utilisateur et collez votre token API comme mot de passe.
- Cliquez sur « Send ». Si tout est correctement configuré, vous devriez voir une réponse JSON avec les détails complets du ticket spécifié, notamment ses champs, commentaires, pièces jointes, etc.
Étape 4 : créer un ticket
Créons maintenant un nouveau ticket via l'API :
- Dans Postman, changez la méthode HTTP en POST et mettez à jour l'URL vers l'endpoint de création de ticket : https://your-domain.atlassian.net/rest/api/3/issue
- Dans l'onglet « Headers », ajoutez une nouvelle paire clé-valeur : « Content-Type » et « application/json ». Cela indique à Jira que nous envoyons une charge utile JSON.
Passez à l'onglet « Body », sélectionnez le bouton radio « raw » et saisissez le JSON suivant, en remplaçant les valeurs project.key, issuetype.name, summary et description selon vos besoins :
json
{
"fields": {
"project": {
"key": "YOUR_PROJECT_KEY"
},
"issuetype": {
"name": "Task"
},
"summary": "Issue created via REST API",
"description": {
"type": "doc",
"version": 1,
"content": [
{
"type": "paragraph",
"content": [
{
"type": "text",
"text": "This is a test issue created using the Jira REST API."
}
]
}
]
}
}
}
3. Cliquez sur « Send ». Jira répondra avec le statut 201 Created et les détails complets du ticket nouvellement créé.
Étape 5 : mettre à jour un ticket
Pour mettre à jour un ticket existant, nous utilisons la méthode PUT :
- Changez la méthode HTTP en PUT et mettez à jour l'URL afin qu'elle pointe vers le ticket que vous souhaitez modifier : https://your-domain.atlassian.net/rest/api/3/issue/ISSUE-KEY
Dans le corps de la requête, incluez les champs que vous souhaitez mettre à jour, par exemple :
json
{
"fields": {
"summary": "Updated summary",
"description": {
"type": "doc",
"version": 1,
"content": [
{
"type": "paragraph",
"content": [
{
"type": "text",
"text": "This issue has been updated via the REST API."
}
]
}
]
}
}
}
2. Cliquez sur « Send ». Jira répondra avec le statut 204 No Content pour indiquer que la mise à jour a réussi.
Étape 6 : rechercher des tickets avec JQL
Les puissantes capacités de recherche de Jira sont également accessibles via l'API REST à l'aide de JQL (Jira Query Language) :
- Remettez la méthode HTTP sur POST et mettez à jour l'URL vers l'endpoint de recherche : https://your-domain.atlassian.net/rest/api/3/search
Dans le corps de la requête, incluez une requête JQL et les éventuels paramètres supplémentaires :
json
Copy
{
"jql": "project = YOUR_PROJECT_KEY AND status = 'To Do' ORDER BY created DESC",
"fields": ["summary", "status", "assignee"],
"maxResults": 10
}
Cette requête renverra les 10 tickets les plus récemment créés avec le statut « To Do » dans le projet spécifié, en incluant uniquement les champs de résumé, de statut et de responsable.
- Cliquez sur « Send ». Jira répondra avec un tableau JSON de tickets correspondant à vos critères de recherche.
Ces exemples ne font qu'effleurer les possibilités de l'API REST Jira. À mesure que vous vous familiariserez avec les endpoints et les paramètres disponibles, vous pourrez créer des intégrations toujours plus complexes et puissantes.
Vous pouvez automatiser Jira sans utiliser d'API sur Latenode
Comment automatiser la création et la mise à jour de tickets Jira avec Latenode
L'une des applications les plus puissantes de l'API REST Jira est l'automatisation de la création et de la mise à jour des tâches. Avec Latenode, vous pouvez configurer des workflows sophistiqués qui créent et mettent automatiquement à jour des tâches dans Jira à partir de données provenant de sources externes ou de déclencheurs spécifiques. Cela garantit que les informations de votre système de gestion de projets restent actuelles et transmises au bon moment, tout en améliorant l'efficacité de l'équipe.
Par exemple, vous pouvez créer un workflow qui génère automatiquement une nouvelle tâche dans Jira lorsqu'un message d'erreur est reçu depuis un système de supervision, renseigne tous les champs nécessaires et attribue la tâche au développeur approprié. Lorsque de nouvelles mises à jour arrivent, la tâche peut être actualisée automatiquement et, une fois le problème résolu, elle peut être clôturée. Cette approche rationalisée améliore non seulement le suivi des tickets, mais fait également gagner du temps à votre équipe, qui peut ainsi se concentrer sur la résolution des problèmes plutôt que sur leur administration.
Vous pouvez en savoir plus sur ce script et sur l'intégration avec Latenode dans cet article. L'intégration avec Latenode offre plusieurs avantages clés :
- Simplicité d'utilisation : Latenode simplifie l'utilisation de l'API de Jira, ce qui permet aux utilisateurs non techniques d'automatiser plus facilement les tâches de gestion de projets.
- Tarification flexible : les utilisateurs peuvent choisir parmi différents forfaits Latenode, aux coûts et fonctionnalités variés, afin de répondre au mieux à leurs besoins.
- Solutions complètes : l'intégration de Latenode avec Jira donne accès à un large éventail de fonctionnalités de gestion de projets et de suivi des tickets.
- Personnalisation : les utilisateurs peuvent adapter les intégrations Jira à leurs besoins spécifiques, afin de créer des solutions d'automatisation sur mesure alignées sur leurs objectifs métier.
Imaginez que chaque e-mail important d'un client soit automatiquement transformé en tâche dans Jira. Avec Latenode, cela devient une réalité. Notre plateforme garantit la création d'une nouvelle tâche dans le bon projet, avec des champs renseignés selon le contenu de l'e-mail, afin qu'aucune demande importante ne soit oubliée.
Voici un exemple de la façon dont un workflow Latenode automatise la création et la mise à jour de tâches Jira à partir de données d'e-mails entrants provenant d'une source externe.
Cette image représenterait visuellement le workflow dans l'interface de Latenode, avec des nœuds connectés représentant chaque étape du processus, de la réception de l'e-mail à la création de la tâche Jira.
Ce n'est qu'un exemple de la manière dont Latenode peut transformer votre utilisation de l'API Jira grâce à une automatisation puissante. En réalité, les possibilités de la plateforme sont pratiquement illimitées : vous pouvez créer tous les workflows d'automatisation nécessaires pour améliorer l'efficacité de votre entreprise. Qu'il s'agisse de distribution automatique des tâches, d'envoi de notifications, de suivi d'indicateurs clés de performance ou de toute autre activité, Latenode fournit les outils nécessaires pour les concrétiser.
En tirant parti du générateur visuel de workflows de Latenode et de son intégration fluide avec l'API REST Jira, vous pouvez facilement concevoir et mettre en œuvre des workflows d'automatisation complexes, accroître l'efficacité de la gestion de projets et accélérer les workflows de votre équipe.
Si vous avez besoin d'aide ou de conseils pour créer votre propre script, ou si vous souhaitez reproduire celui-ci, contactez notre communauté Discord, où se trouvent des experts de l'automatisation low-code.
Pagination, expansion et tri dans l'API REST Jira
Lorsque vous commencerez à travailler avec des ensembles de données plus volumineux dans Jira, vous devrez comprendre comment l'API REST gère la pagination, l'expansion des ressources imbriquées et le tri des résultats.
Expansion
De nombreuses ressources Jira contiennent des références à d'autres ressources imbriquées. Par exemple, un ticket contient des références à son projet, son type de ticket, son créateur, son rapporteur, son responsable, ses commentaires, ses pièces jointes, etc. Par défaut, ces ressources imbriquées sont renvoyées sous forme de versions réduites, ne contenant que quelques champs de base et un lien self vers la ressource complète.
Si vous avez besoin des détails complets d'une ressource imbriquée, vous pouvez utiliser le paramètre de requête expand pour demander à Jira d'inclure la ressource complète dans la réponse. Par exemple, pour inclure les détails complets du projet et du responsable d'un ticket :
GET .../rest/api/3/issue/ISSUE-KEY?expand=project,assignee
Vous pouvez développer plusieurs ressources en les séparant par des virgules. Gardez à l'esprit que les expansions peuvent considérablement augmenter la taille de la charge utile de réponse ; utilisez-les donc avec discernement.
Pagination
Les requêtes susceptibles de renvoyer un grand nombre de résultats, comme les recherches JQL, sont paginées par défaut. L'API renvoie un nombre maximal de résultats par page (50 par défaut, mais personnalisable jusqu'à 100), ainsi que des liens vers les pages suivante et précédente.
Vous pouvez contrôler la pagination à l'aide des paramètres startAt et maxResults :
- startAt : l'index du premier résultat à renvoyer (à partir de 0)
- maxResults : le nombre maximal de résultats à renvoyer par page
Par exemple, pour récupérer la deuxième page de résultats avec une taille de page de 20 :
GET .../rest/api/3/search?jql=project=YOUR_PROJECT_KEY&startAt=20&maxResults=20
Votre application devra gérer plusieurs requêtes afin de récupérer toutes les pages de résultats.
Tri
Vous pouvez contrôler l'ordre des résultats à l'aide du paramètre orderBy, qui accepte une liste de champs séparés par des virgules pour définir le tri. Chaque champ peut être précédé d'un - pour indiquer un ordre décroissant.
Par exemple, pour trier les tickets par date de création décroissante, puis par priorité croissante :
GET .../rest/api/3/search?jql=project=YOUR_PROJECT_KEY&orderBy=-created,priority
Tous les champs ne prennent pas en charge le tri : consultez la documentation de l'endpoint concerné pour voir les options disponibles.
Exemples d'utilisation de l'API Jira
Voici quelques exemples plus avancés démontrant la puissance de l'API REST Jira pour les opérations en masse.
Création/mise à jour en masse de tickets depuis un fichier CSV
Supposons que vous disposiez d'un fichier CSV contenant les données de plusieurs tickets que vous souhaitez créer ou mettre à jour dans Jira. Vous pouvez utiliser un outil comme Postman pour automatiser ce processus :
- Dans Postman, créez une nouvelle requête pour l'endpoint de création ou de mise à jour de tickets.
Dans l'onglet Body, sélectionnez le bouton radio « raw » et saisissez un modèle pour les données de votre ticket, en utilisant des variables pour les champs provenant de votre fichier CSV :
{
"fields": {
"project": {"key": "{{project_key}}"},
"issuetype": {"name": "{{issue_type}}"},
"summary": "{{summary}}",
"description": {
"type": "doc",
"version": 1,
"content": [
{
"type": "paragraph",
"content": [
{
"type": "text",
"text": "{{description}}"
}
]
}
]
},
"assignee": {"name": "{{assignee}}"},
"priority": {"name": "{{priority}}"}
}
}
2. Passez à l'onglet « Pre-request Script » et ajoutez le code permettant de lire votre fichier CSV et de définir les variables correspondantes :
const csvFile = pm.iterationData.readCSV();
pm.variables.set('project_key', csvFile[0]);
pm.variables.set('issue_type', csvFile[1]);
pm.variables.set('summary', csvFile[2]);
pm.variables.set('description', csvFile[3]);
pm.variables.set('assignee', csvFile[4]);
pm.variables.set('priority', csvFile[5]);
3. Dans la fenêtre « Runner », sélectionnez votre fichier CSV comme fichier de données et lancez l'exécution. Postman créera une nouvelle requête pour chaque ligne de votre fichier CSV, en remplaçant les variables par les valeurs du fichier.
Il s'agit d'une technique puissante pour importer en masse des données provenant de sources externes dans Jira.
Création/mise à jour en masse de tickets depuis JSON
Si vos données sources sont déjà au format JSON, vous pouvez utiliser l'endpoint de création/mise à jour en masse pour traiter plusieurs tickets dans une seule requête :
POST https://your-domain.atlassian.net/rest/api/3/issue/bulk
Le corps de la requête doit contenir un tableau d'objets de création/mise à jour de tickets, chacun suivant le même format qu'une requête de création/mise à jour d'un seul ticket :
{
"issueUpdates": [
{
"fields": {
"project": {"key": "PROJ1"},
"issuetype": {"name": "Task"},
"summary": "Issue 1",
"description": {
"type": "doc",
"version": 1,
"content": [
{
"type": "paragraph",
"content": [
{
"type": "text",
"text": "First issue created via bulk update"
}
]
}
]
}
}
},
{
"fields": {
"project": {"key": "PROJ2"},
"issuetype": {"name": "Bug"},
"summary": "Issue 2",
"description": {
"type": "doc",
"version": 1,
"content": [
{
"type": "paragraph",
"content": [
{
"type": "text",
"text": "Second issue created via bulk update"
}
]
}
]
},
"priority": {"name": "High"},
"labels": ["bulk-import", "api-test"]
}
}
]
}
Cette requête créera deux tickets en une seule opération : une tâche dans le projet PROJ1 et un bug dans le projet PROJ2. Vous pouvez inclure jusqu'à 50 tickets dans une seule requête groupée.
L'endpoint de traitement en masse est également utile pour effectuer des transitions, mises à jour et suppressions en masse. Par exemple, pour faire passer plusieurs tickets au statut « Done » :
{
"transition": {
"id": "31"
},
"issues": [
{"key": "ISSUE-1"},
{"key": "ISSUE-2"},
{"key": "ISSUE-3"}
]
}
Cela suppose que « 31 » est l'ID de votre transition « Done ». Vous pouvez trouver les transitions disponibles pour un type de ticket via l'endpoint /rest/api/3/issue/{issueIdOrKey}/transitions.
Résumé
L'API REST Jira est un outil extrêmement puissant pour intégrer Jira à d'autres systèmes, automatiser des tâches et étendre les capacités de Jira. Dans ce guide, nous avons présenté les fondamentaux de l'API, notamment :
- La différence entre les API Java et REST, et quand utiliser chacune d'elles
- Les principales différences entre les API Cloud et Server/Data Center
- Comment vous authentifier auprès de l'API à l'aide de tokens API ou de Basic Auth
- L'exécution de vos premières requêtes API avec Postman
- La création, la récupération, la mise à jour et la recherche de tickets
- La gestion de la pagination, de l'expansion et du tri des résultats
- Des cas d'utilisation avancés, comme la création/mise à jour en masse à partir de données CSV et JSON
Cependant, nous n'avons fait qu'effleurer le sujet. L'API REST Jira fournit des endpoints pour travailler avec presque tous les aspects de Jira, des projets et tableaux aux utilisateurs et autorisations. Lorsque vous créez vos intégrations, veillez à consulter la documentation officielle d'Atlassian pour obtenir les informations les plus récentes et les plus complètes.
Avec l'API REST Jira dans votre boîte à outils, les possibilités offertes par Jira sont presque infinies. Que vous créiez un tableau de bord de reporting personnalisé, synchronisiez des données avec un autre système ou automatisiez des workflows complexes, l'API vous apporte la flexibilité et la puissance nécessaires pour y parvenir.
Vous pouvez essayer Jira sans utiliser d'API sur Latenode
