Haut de page

API REST JIRA : Comment ça fonctionne ?


Publié par
Marcus Hilliges

13 juin 2018

Chez Valiantys, nous utilisons l’API REST de Jira pour accomplir des tâches répétitives comme créer des tickets avec de nombreuses pièces-jointes ou lorsque nous développons des apps pour Jira. Nous avons également remarqué que certains de nos clients utilisaient l’API REST pour créer des rapports spécifiques ou pour synchroniser leurs tickets Jira avec d’autres systèmes.

Le moment est donc venu de présenter l’API REST Jira un peu plus en détails.

L’API REST : qu’est-ce que c’est?

Le REST (Representational State Transfer) est un style d’architecture que l’on peut comparer à un système de communication qui est souvent utilisé dans le développement de services Web.  C’est le paradigme API le plus utilisé sur le web. On y a régulièrement recours afin de connecter les apps sur le Cloud.  Au début de l’année, les développeurs Atlassian ont annoncé un nouveau module avec une interface API REST, décrit comme beaucoup plus simple à implémenter et à maintenir.

Jira donne accès à une large gamme de ressources REST qui aident les développeurs à faire communiquer Jira avec d’autres applications. Avec ces ressources vous pouvez créer, améliorer, corriger et supprimer des données dans Jira en utilisant des méthodes HTTP standards comme GET, PUT, POST et DELETE.

Le Navigateur API REST d’Atlassian

Atlassian REST API Browser  donne accès à un navigateur avec les différentes ressouces REST disponibles sur Jira. Après avoir installé l’app, allez dans Système > Section Avancée > Navigateur API REST. Vous devriez voir ceci : 

API Browser

 

Il faut cliquer sur le lien Drop Access dans le message d’information afin que de la barre de recherche API, que vous voyez ci-dessous, puisse apparaître. 

 

search barEt maintenant passons aux choses sérieuses !

Tout d’abord vous devez définir l’action que vous essayez d’accomplir – par exemple : créer un ticket, joindre un document, ajouter un utilisateur ou obtenir une information sur un champ personnalisé spécifique.

Pour ce tutoriel nous allons créer un ticket en utilisant le REST. Afin d’obtenir la bonne ressource API, vous pouvez utiliser le navigateur API de l’Atlassian Developer Toolbox app ou consulter la documentation Atlassian sur Jira REST API.

 

Create API

 

Comme vous pouvez le constater sur la capture d’écran ci-dessus, lorsque que vous écrivez le mot create, nous surlignons automatiquement l’action à effectuer sur l’API. Sur le côté droit vous verrez une brève description de l’API, les options de paramétrage et la méthode HTTP qui doit être utilisée pour réaliser la demande avec succès.

Pour cet exemple, les paramètres ne sont pas obligatoires, cependant vous pouvez utiliser la méthode HTTP POST afin de créer le ticket.

A présent, construisons le corps de notre requête en utilisant le format JSON afin de créer un ticket. Ci-dessous, vous trouverez la configuration de notre Jira :

Project/Custom field Name

Key/ID

Test Project

TP

REST API

10100

Un échantillon de la requête JSON :

{ "fields": { "project": { "key": "TP" }, "summary": "Summary of the issue created using REST API...", "description": "Description of the issue", "issuetype": { "id": "3" }, "assignee": { "name": "admin" }, "reporter": { "name": "admin" }, "priority": { "id": "1" }, "customfield_10100": "DATA INSERTED INTO REST API CUSTOM FIELD" } }

Grâce au code JSON ci-dessus, nous avons pu établir la Clé Projet Jira, le Résumé, la Description, le Type de demande, l’Attribution, le Rapporteur, les champs Priorité et un champ personnalisé (dont le nom est : REST API).

Request Body

 

Ecrivez ou copiez l’exemple JSON ci-dessus dans le Corps de la Requête dans votre navigateur puis changez les valeurs comme le nom du ticket, le type, la priorité, le champ personnalisé et la clé projet afin que ces dernières correspondent à votre instance Jira. Une fois que c’est fait, cliquez sur Envoyer et vous devriez recevoir ce message: 

 

response

 

Le message de réponse doit montrer l’ID, la clé et l’URL entière du nouveau ticket. Vous pouvez utiliser l’URL pour trouver le ticket lié au projet.

 

CF

 

Félicitations, vous avez réussi à créer un ticket en utilisant l’API REST Jira !

Clients REST

Une alternative serait d’utiliser les extensions clients REST de vos navigateurs ou applications pour exécuter vos opérations. Par exemple, l’extension Advanced Rest Client de Chrome permet d’envoyer des requêtes personnalisées depuis votre navigateur vers n’importe quelle application qui supporte REST. 

Nous utiliserons l’URL du REST pour créer un ticket depuis l’exemple précédent:

http://localhost:8080/rest/api/2/issue


Après avoir installé l’extension dans Chrome, vous devriez voir la capture ci-dessous :

ARC

Ci-dessous les différentes sections que nous allons utiliser pour créer un ticket Jira.

 

Name Data

URL

http://localhost:8080/rest/api/2/issue

HTTP method

POST

Header

admin:admin

Request Body

{ « fields »: { « project »: { « key »: « TP » }, « summary »: « REST API TEST », « description »: « Creating of a ticket using project keys and issue type names using the REST API », « issuetype »: { « id »: « 3 » }, « assignee »: { « name »: « admin » }, « reporter »: { « name »: « admin » }, « priority »: { « id »: « 1 » }, « customfield_10100 »: « DATA INSERTED INTO REST API CUSTOM FIELD » } }

La seule différence entre l’application Atlassian REST API Browser et le Advanced REST Client se trouve dans le nom d’utilisateur. Ce dernier est requis dans la section d’en-tête, comme vous pouvez le voir dans le tableau ci-dessus (nom d’utilisateur:mot de passe).  Vu que nous créons les données  à l’extérieur de Jira, vous devez vous assurer que l’utilisateur a la permission de créer des tickets dans Jira. (Note: les deux points sont nécessaires entre le nom d’utilisateur et le mot de passe).

La requête finale devrait ressembler à cela :

 

ChromeExRequest

 

Après avoir cliqué sur Envoyer, ce message de réponse devrait apparaître :

 

ChromeExResponse

 

API REST Jira : la suite

Vous venez d’apercevoir une des possiblités qu’offrent les ressources REST proposées par Jira et les autres outils Atlassian. Pour retrouver ces ressources et d’autres exemples d’utilisation de ces dernières, voici quelques liens :

Pour d’autres astuces Atlassian, inscrivez-vous à notre newsletter :