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 :
Et 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.
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 :
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).
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:
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.
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 :
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 :
Après avoir cliqué sur Envoyer, ce message de réponse devrait apparaître :
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 :
- Jira REST API documentation
- Jira REST API Tutorials
- Confluence REST API documentation
- Confluence REST API Examples
Pour d’autres astuces Atlassian, inscrivez-vous à notre newsletter :
Je souhaite recevoir les nouvelles d’Atlassian
