API REST Atlassian JIRA


Publié par
Corentin BRESSON

15 février 2012

Un des points forts de la prochaine version de JIRA sera son API REST, qui a été entièrement remaniée. L’accent est mis sur sa fiabilité et sa stabilité. C’est l’API distante pour JIRA 5.0+ supportée et recommandée par Atlassian: l’éditeur y concentrera ses efforts de résolution des bugs et d’ajout de fonctionnalité.

Saisissons l’occasion pour introduire brièvement cette API, dérouler deux exemples de création de demande et présenter le « navigateur » des ressources REST de votre application.

API REST JIRA

API REST JIRA

Qu’est-ce que REST ?

L’API REST est destinée aux développeurs qui souhaitent ajouter des fonctionnalités  supplémentaires à JIRA. Elle permet, entre autres, la création, l’édition, la mise à jour et la suppression de demandes ainsi que la manipulation de metadata. Les API REST fournissent un moyen facile et léger d‘intégration avec d’autres applications -web, mobile ou desktop, extensions de navigateur, plugins Atlassian- en utilisant les méthodes standards HTTP et le format JSON. Elles peuvent donc être utilisées avec n’importe quelle langage de programmation ou framework.

Vos plugins

JIRA utilise le plugin Atlassian REST pour implémenter l’API. Il est inclus dans JIRA5. Si vous souhaitez ajouter vos propres API REST dans JIRA, créez un plugin JIRA qui inclus le plugin Atlassian REST, en vous référant aux recommandations Atlassian en matière de design d’API REST.

Première approche

Pour une introduction générale et comparative de REST (vs SOAP), un point de départ possible est ce post de Dare Obasanjo (en anglais).

Création de demande: deux exemples

Rien de plus simple que de créer une demande JIRA avec REST:

  • Le fichier d’entrée est noté avec la syntaxe –data @filename. Les données sont ici montrées séparément; elles utilisent le format JSON.
  • Le type de contenu de la requête doit être application/json
  • Poster le JSON au serveur. Dans cet exemple, le serveur est http://localhost:8090/rest/api/2/issue/
  • Les deux exemples utilisent une authentification de base, avec un username fred et un mot de passe fred.
  • Les exemples utilisent curl.

Exemple 1: Utilisation des IDs

Ce premier exemple créée une demande en spécifiant l’ID du projet et l’ID du type de demande.

Requête:

curl -D- -u fred:fred -X POST –data {cf ci-dessous} -H « Content-Type: application/json » http://localhost:8090/rest/api/2/issue/

Data (JSON):

{
« fields »: {
<strong> « project »:
{
« id »: « 10110 »</strong>
},
« summary »: « I need some REST… »,
« description »: « Création d’une demande en utilisant l’ID du projet et l’ID du type de demande, grâce à l’API REST »,
<strong> « issuetype »: {
« id »: « 1 »</strong>
}
}
}

La réponse fournit l’ID de la demande, sa clé et l’URI de la demande, qui peut être utilisée pour récupérer des données additionnelles via GET, pour de l’édition via PUT etc.:

{
« id »: »39001″,
« key »: »TEST-102″,
« self »: »http://localhost:8090/rest/api/2/issue/TEST-102″
}</p>
<h3>Exemple 2: Utilisation de la Clé de projet et des Noms de champs (Project Key and Field Names)</h3>
<p>Il est possible de créer une demande en spécifiant la clé du projet et le nom des champs. La requête, suivie du JSON:</p>
<pre class="brush: java; html-script: true;">curl -D- -u fred:fred -X POST --data {see below} -H "Content-Type: application/json" http://localhost:8090/rest/api/2/issue/
{
"fields": {
<strong> "project":
{
"key": "TEST"</strong>
},
"summary": "Give me a REST!!",
"description": "Création d'une demande en utilisant le project keys et le nom de type de demande, grâce à l'API REST",
<strong>"issuetype": {
"name": "Bug"</strong>
}
}
}
Réponse:
{
"id":"39000",
"key":"TEST-101",
"self":"http://localhost:8090/rest/api/2/issue/TEST-101"
}

Plus d’information sur la creation de demandes via REST. Les instructions relatives à la mise à jour de demandes sont également valables pour leur édition.

Naviguer et tester vos API REST à partir de l’interface de votre application.

"RAB" (pour "REST API Browser") est un outil Atlassian permettant de découvrir les API REST et les autres API distantes disponibles dans l'instance d’une application Atlassian (JIRA, Confluence etc). RAB est un plugin de l’application hôte.

RAB dévoile toutes les ressources JSON et REST d’une application, expose les méthodes de chaque ressource et permet de faire des appels test vers elles. Si vous avez installé un plugin qui crée des ressources REST additionnelles, RAB les trouvera également.

Démarrage rapide

Vous utilisez le plugin Atlassian Plugin SDK ? Alors vous avez déjà RAB. Voici quelques instructions pour commencer à l’utiliser rapidement :

  1. Commencer par un atlas-run, un atlas-debug ou bien un atlas-run-standalone, comme vous en avez l’habitude. Les applications Atlassian seront installées avec le plugin "REST API Browser" activé.
  2. Aller dans l’écran d’administration de votre application.
  3. Cliquer sur “REST API Browser”
  4. Choisir une API dans la liste déroulante en haut à droite de l’écran.
  5. Choisir une ressource dans la liste à gauche de l’écran. Le RAB montrera les méthodes (GET, POST, PUT, etc) et les paramètres disponibles pour cette méthode.
  6. Pour tester la ressource, entrer les valeurs de paramètres comme demandé et cliquer sur « Execute ».

Pour des instructions détaillées, se référer à la documentation RAB.

Ressources

Quelques pointeurs vers la documentation de l'éditeur (en anglais):