API REST

Des scripts, des intégrations et d'autres outils hors de Jira peuvent lire et modifier les hiérarchies TreeCraft grâce à l'API REST de l'application. Cette page s'adresse aux développeurs qui les créent. Elle explique comment activer l'API et obtenir un jeton, puis présente les portées, chaque point de terminaison et les règles que suit chaque appel.

À quoi sert l'API

L'API permet à un programme de faire ce qu'une personne fait dans les pages de l'application, en son nom. Par exemple, elle peut :

• lister les hiérarchies qu'une personne peut ouvrir, et lire leurs lignes ;
• garder une hiérarchie synchronisée avec un autre outil, en ajoutant, en déplaçant et en retirant des lignes ;
• créer, renommer, archiver ou supprimer des hiérarchies ;
• lire les règles d'une hiérarchie et les vues enregistrées.

Chaque appel agit au nom de la personne qui l'a autorisé, avec les mêmes vérifications que les pages de l'application :

• son niveau d'accès sur la hiérarchie : Consulter, Modifier, Automatiser ou Contrôler ;
• les réglages Accès à l'app et Droits d'automatisation du site ;
• ses permissions Jira sur chaque ticket.

Une ligne ne montre jamais un ticket que la personne ne peut pas voir dans Jira. L'API renvoie l'identifiant des tickets, pas leurs champs : lisez les tickets eux-mêmes avec l'API REST de Jira et le même jeton, pour que les permissions de Jira s'y appliquent aussi.

Il s'agit de la version 1, en bêta. L'API repose sur les API REST d'applications Forge, qu'Atlassian propose en préversion. Atlassian peut les modifier avec un préavis plus court que d'habitude : l'API reste donc en bêta tant qu'elles ne sont pas offertes à tous.

Elle fonctionne sur Atlassian

Les appels passent par la passerelle d'API d'Atlassian jusqu'à l'application, qui fonctionne sur le nuage d'Atlassian comme le reste de TreeCraft. L'application n'envoie aucune donnée hors d'Atlassian. Ce que l'API conserve, par exemple la trace d'un appel répété, reste dans le stockage de l'application chez Atlassian, avec le reste des données du site. Avec l'API activée, TreeCraft reste conçu selon les exigences du programme Runs on Atlassian.

La passerelle vérifie le jeton et ses portées avant que l'appel n'atteigne l'application. Un jeton qui n'a pas la portée exigée par une route n'atteint jamais TreeCraft.

Activer l'API

Deux interrupteurs doivent être activés pour qu'un appel atteigne l'application. Les deux appartiennent au site, et désactiver l'un ou l'autre arrête aussitôt tous les appels.

La première version de TreeCraft qui comprend l'API est une mise à jour majeure de l'application. Un administrateur du site approuve cette mise à jour une fois avant que l'API ne soit disponible.

L'interrupteur d'Atlassian

L'interrupteur d'Atlassian est désactivé par défaut. Un administrateur du site ou de l'organisation l'active :

1. Dans Atlassian Administration, sélectionnez votre organisation.
2. Sous Applications, allez dans Sites et sélectionnez le site où TreeCraft est installé.
3. Sélectionnez Applications connectées, trouvez TreeCraft et ouvrez les détails de l'application.
4. Dans l'onglet Détails, activez App REST APIs.

L'interrupteur de TreeCraft

L'interrupteur de TreeCraft est activé par défaut. Les administrateurs Jira et les administrateurs de l'application le trouvent dans les paramètres de l'application, dans l'administration de Jira sous Applications : sélectionnez API REST dans le groupe Accès. La page présente :

• Autoriser les appels à l'API REST de cette application sur ce site, l'interrupteur. Une modification s'applique à tous les appels en moins d'une minute. Tant qu'il est désactivé, chaque appel répond 403 API_TURNED_OFF.
• URL de base, sous ses deux formes, remplies pour votre site, chacune avec un bouton de copie.
• Identifiants : l'identifiant de l'application, l'identifiant de l'environnement et l'identifiant cloud.
• Portées : les trois portées et ce que chacune permet.

Obtenir un jeton d'accès

L'API accepte un jeton d'accès OAuth 2.0 (3LO). Un jeton appartient à une personne, et chaque appel fait avec lui agit en son nom. Seuls les membres du site où TreeCraft est installé peuvent configurer l'intégration. Les libellés de l'Atlassian Developer Console sont donnés ici en anglais.

1. Ouvrez l'Atlassian Developer Console. Sélectionnez Create, puis OAuth 2.0 integration, et nommez l'intégration.
2. Sous Permissions, sélectionnez Add Marketplace or custom app. Choisissez votre site, puis TreeCraft, puis les portées dont votre intégration a besoin. Ne choisissez que celles-là.
3. Ajoutez aussi la portée Jira read:forge-app:jira. Tout appel à l'API REST d'une application l'exige.
4. Sous Authorization, indiquez une URL de rappel. La console affiche alors une URL d'autorisation.
5. Vérifiez que le paramètre scope de cette URL contient les portées TreeCraft et read:forge-app:jira. Ajoutez offline_access pour obtenir un jeton d'actualisation. Ajoutez à la main toute portée manquante, en les séparant par %20.
6. Ouvrez l'URL, choisissez le site et sélectionnez Accept. Atlassian vous renvoie vers l'URL de rappel avec un code.
7. Échangez ce code contre un jeton, comme le montre l'exemple ci-dessous.

Une URL d'autorisation qui demande la portée de lecture ressemble à ceci :

https://auth.atlassian.com/authorize?audience=api.atlassian.com&client_id=YOUR_CLIENT_ID&scope=read%3Ahierarchy%3Acustom%20read%3Aforge-app%3Ajira%20offline_access&redirect_uri=YOUR_CALLBACK&state=RANDOM&response_type=code&prompt=consent

Échangez le code contre un jeton de cette façon :

curl -s -X POST https://auth.atlassian.com/oauth/token \
  -H 'Content-Type: application/json' \
  -d '{"grant_type":"authorization_code","client_id":"YOUR_CLIENT_ID","client_secret":"YOUR_CLIENT_SECRET","code":"THE_CODE","redirect_uri":"YOUR_CALLBACK"}'

La réponse contient access_token, de courte durée, et refresh_token si vous avez demandé offline_access. Pour obtenir un nouveau jeton d'accès, envoyez le jeton d'actualisation à la place du code :

curl -s -X POST https://auth.atlassian.com/oauth/token \
  -H 'Content-Type: application/json' \
  -d '{"grant_type":"refresh_token","client_id":"YOUR_CLIENT_ID","client_secret":"YOUR_CLIENT_SECRET","refresh_token":"THE_REFRESH_TOKEN"}'

Envoyez le jeton à chaque appel, dans l'en-tête Authorization :

curl -s "$BASE/v1/hierarchies" -H "Authorization: Bearer $TOKEN" -H 'Accept: application/json'

Si le jeton n'a pas la portée exigée par une route, la passerelle d'Atlassian refuse l'appel avec 401 Unauthorized; scope does not match.

URL de base

Deux formes d'URL de base mènent à la même API :

https://api.atlassian.com/svc/jira/<cloud-id>/apps/<app-id>_<environment-id>
https://<your-site>.atlassian.net/gateway/api/svc/jira/apps/<app-id>_<environment-id>

Les parties entre chevrons sont à remplacer. Vos propres valeurs figurent dans la page API REST de TreeCraft, qui affiche les deux URL déjà remplies, prêtes à copier.

Une fois l'interrupteur d'Atlassian activé, Atlassian Administration affiche aussi l'URL de base sous App REST APIs.

Les exemples de cette page utilisent deux variables du shell :

BASE='https://api.atlassian.com/svc/jira/<cloud-id>/apps/<app-id>_<environment-id>'
TOKEN='<access-token>'

Portées

TreeCraft a trois portées. Chaque point de terminaison exige exactement l'une d'elles.

Une portée ne donne jamais plus que ce que la personne a déjà. Une intégration qui modifie des lignes demande d'habitude aussi read:hierarchy:custom, pour lire ce qu'elle modifie. Chaque appel exige en plus la portée Jira read:forge-app:jira.

Points de terminaison

Chaque chemin commence par la version, /v1. {id} est l'identifiant d'une hiérarchie et {viewId} celui d'une vue. Le niveau est le niveau d'accès de la personne sur la hiérarchie. Chaque appel exige aussi qu'Accès à l'app permette à la personne d'utiliser l'application.

Une hiérarchie que la personne ne peut pas ouvrir répond 404, comme une hiérarchie qui n'existe pas. Un niveau trop bas répond 403.

Lister les hiérarchies

GET /v1/hierarchies · Portée : read:hierarchy:custom · Exige : Consulter sur chaque hiérarchie listée

Liste les hiérarchies que la personne peut ouvrir, par ordre d'identifiant, une page à la fois.

curl -s "$BASE/v1/hierarchies?limit=2" -H "Authorization: Bearer $TOKEN"

{
  "hierarchies": [
    { "id": 12, "name": "Plan de livraison", "description": "", "ownerAccountId": "5b10ac8d82e05b22cc7d4ef5", "access": "control",
      "archived": false, "version": 48, "labels": ["Planification"], "favorite": true, "searchable": false },
    { "id": 15, "name": "Demandes de support", "description": "Demandes ouvertes par équipe", "ownerAccountId": "5b10ac8d82e05b22cc7d4ef5",
      "access": "view", "archived": false, "version": 7, "labels": [], "favorite": false, "searchable": true }
  ],
  "nextCursor": "aDoxNQ"
}

Chaque hiérarchie a ces champs :

Créer une hiérarchie

POST /v1/hierarchies · Portée : manage:hierarchy:custom · Exige : Accès à l'app permet à la personne de créer des hiérarchies

Crée une hiérarchie. La personne en devient propriétaire, avec Contrôler, et la hiérarchie s'ajoute à ses favoris. Comme toute nouvelle hiérarchie, elle est privée au départ.

curl -s -X POST "$BASE/v1/hierarchies" -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' -H 'Idempotency-Key: creer-plan-livraison-1' \
  -d '{"name":"Plan de livraison","description":"Tout ce qui est prévu pour la prochaine version"}'

Répond 201 avec la nouvelle hiérarchie :

{ "id": 21, "name": "Plan de livraison", "description": "Tout ce qui est prévu pour la prochaine version", "ownerAccountId": "5b10ac8d82e05b22cc7d4ef5",
  "access": "control", "archived": false, "version": 0, "labels": [], "favorite": true, "searchable": false }

Obtenir une hiérarchie

GET /v1/hierarchies/{id} · Portée : read:hierarchy:custom · Exige : Consulter

Lit les détails d'une hiérarchie. Cet appel coûte peu : c'est un bon moyen de vérifier version avant de relire les lignes.

curl -s "$BASE/v1/hierarchies/12" -H "Authorization: Bearer $TOKEN"

Répond 200 avec la hiérarchie, avec les mêmes champs que dans la liste :

{ "id": 12, "name": "Plan de livraison", "description": "", "ownerAccountId": "5b10ac8d82e05b22cc7d4ef5", "access": "control",
  "archived": false, "version": 48, "labels": ["Planification"], "favorite": true, "searchable": false }

Modifier une hiérarchie

PATCH /v1/hierarchies/{id} · Portée : manage:hierarchy:custom · Exige : Contrôler

Renomme une hiérarchie, change sa description ou ses étiquettes, l'archive ou la restaure. Donnez au moins un champ.

Les champs s'appliquent l'un après l'autre, comme dans l'application. Une erreur 400 pour un name ou une description incorrects peut donc arriver alors que les étiquettes (labels) de la même demande ont déjà été modifiées. Quand cela compte, envoyez un seul champ à la fois.

curl -s -X PATCH "$BASE/v1/hierarchies/12" -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' -d '{"name":"Plan de livraison 2027","labels":["Planification","2027"]}'

Répond 200 avec la hiérarchie telle qu'elle est maintenant :

{ "id": 12, "name": "Plan de livraison 2027", "description": "", "ownerAccountId": "5b10ac8d82e05b22cc7d4ef5", "access": "control",
  "archived": false, "version": 48, "labels": ["Planification", "2027"], "favorite": true, "searchable": false }

Supprimer une hiérarchie

DELETE /v1/hierarchies/{id} · Portée : manage:hierarchy:custom · Exige : Contrôler

Supprime la hiérarchie avec ses lignes, ses règles et ses écritures en retour. Les tickets Jira ne changent pas. La suppression est définitive.

curl -s -X DELETE "$BASE/v1/hierarchies/12" -H "Authorization: Bearer $TOKEN"

Répond 204, sans corps.

Lire les lignes

GET /v1/hierarchies/{id}/rows · Portée : read:hierarchy:custom · Exige : Consulter

Lit l'arbre, ou la partie qui se trouve sous une ligne. Les lignes arrivent dans l'ordre où la grille les affiche sans tri : chaque ligne, puis les lignes qui se trouvent sous elle.

curl -s "$BASE/v1/hierarchies/12/rows?depth=2&limit=5000" -H "Authorization: Bearer $TOKEN"

{
  "hierarchyId": 12,
  "version": 48,
  "building": false,
  "limitsReached": [],
  "rows": [
    { "id": 4711, "parentId": null, "level": 1, "kind": "issue", "byRule": false, "hasChildren": true, "issueId": "10001" },
    { "id": 4712, "parentId": 4711, "level": 2, "kind": "folder", "byRule": false, "hasChildren": false, "folderId": "7", "name": "Trimestre prochain" },
    { "id": 4713, "parentId": 4711, "level": 2, "kind": "restricted", "byRule": false, "hasChildren": true },
    { "id": 4800, "parentId": null, "level": 1, "kind": "group", "byRule": true, "hasChildren": true, "groupId": "status:3", "label": "En cours" }
  ],
  "nextCursor": null
}

Chaque ligne a ces champs :

Puis, selon le type :

La réponse contient aussi :

• version : la version de la hiérarchie au moment où la page a été lue.
• building : true pendant la reconstruction des résultats des règles. Relisez un peu plus tard pour obtenir les lignes les plus récentes.
• limitsReached : les limites des règles qui ont coupé les résultats des règles, sous les noms qu'emploie l'avis de l'application.

Chaque page relit l'arbre : demandez donc de grandes pages. Une hiérarchie de 20 000 lignes se lit en 4 appels de 5 000.

Modifier les lignes

POST /v1/hierarchies/{id}/rows/batch · Portée : write:hierarchy:custom · Exige : Modifier, et Automatiser pour déplacer ou retirer des règles

Ajoute, déplace et retire des lignes en un seul lot. L'application vérifie d'abord le lot entier, puis l'écrit en une seule modification, ou pas du tout. C'est la même modification, avec les mêmes vérifications, qu'une modification faite dans l'application.

Chaque changement a une action :

curl -s -X POST "$BASE/v1/hierarchies/12/rows/batch" -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' -H 'Idempotency-Key: sync-2026-10-24-0900' \
  -d '{"changes":[
        {"action":"add","parentId":null,"afterId":4711,"items":[{"issueId":"10001"},{"folderName":"Trimestre prochain"}]},
        {"action":"move","rowIds":[4712],"parentId":4800,"afterId":null},
        {"action":"remove","rowIds":[4713],"keepChildren":true}]}'

{
  "hierarchyId": 12,
  "version": 49,
  "added": [
    { "changeIndex": 0, "rowId": 6620417819, "kind": "issue", "issueId": "10001" },
    { "changeIndex": 0, "rowId": 2299815532, "kind": "folder", "folderId": "8" }
  ],
  "removedRowIds": [4713]
}

added liste les nouvelles lignes, avec l'indice du changement qui a ajouté chacune. C'est l'application qui choisit l'identifiant des nouvelles lignes. removedRowIds ne liste que les lignes que la personne pouvait voir.

• La personne doit pouvoir voir chaque ligne que le lot nomme, les lignes au-dessus d'elle et chaque ticket qu'il ajoute. Sinon, le lot répond 403 et ne modifie rien.
• Une ligne qui n'existe plus répond 409 CONFLICT.
• Un lot compte au plus 200 changements, 2 000 lignes et 50 nouveaux dossiers.
• Une hiérarchie contient au plus 20 000 tickets.
• Les lignes que la personne ne peut pas voir sous une ligne retirée restent où elles étaient, comme dans l'application.
• Les nouveaux dossiers indiqués par folderName sont créés avant que la modification ne soit écrite. Si le lot est refusé, ils sont supprimés de nouveau.
• Les modifications dans les résultats des règles exigent le paramètre de la hiérarchie qui les permet. Voir Modifications dans le résultat des règles.
• Une hiérarchie qui a des règles reconstruit ensuite leurs résultats, en arrière-plan.

Lister les règles

GET /v1/hierarchies/{id}/rules · Portée : read:hierarchy:custom · Exige : Automatiser

Liste les règles de la hiérarchie dans l'ordre de l'arbre, avec leurs paramètres. Il faut Automatiser, comme pour les paramètres des règles dans l'application.

curl -s "$BASE/v1/hierarchies/12/rules" -H "Authorization: Bearer $TOKEN"

{
  "hierarchyId": 12,
  "version": 48,
  "building": false,
  "limitsReached": [],
  "rules": [
    { "ruleId": "31", "rowId": 4800, "parentId": null, "position": 0, "type": "insertJql", "settings": { "type": "insertJql", "jql": "project = REL" } }
  ]
}

Chaque règle a son ruleId, son rowId dans l'arbre, son parentId, sa position parmi ses sœurs (à partir de 0), son type et ses settings tels que l'application les conserve. Les versions suivantes pourront ajouter des champs à settings.

Lister les vues

GET /v1/views · Portée : read:hierarchy:custom · Exige : aucun niveau sur une hiérarchie

Liste toutes les vues de la personne et jusqu'à 100 vues partagées qu'elle peut utiliser.

curl -s "$BASE/v1/views?search=livraison" -H "Authorization: Bearer $TOKEN"

{
  "views": [
    { "id": 4, "name": "Colonnes de livraison", "mine": true, "shared": true, "editable": true,
      "columns": [ { "id": "c1", "type": "field", "field": "status" } ], "wrap": false }
  ],
  "moreShared": false
}

mine vaut true pour les vues de la personne, shared pour les vues partagées avec d'autres, et editable quand la personne peut modifier la vue dans l'application. columns liste ses colonnes dans l'ordre, telles que l'application les conserve. moreShared vaut true quand il existe plus de vues partagées que celles listées : cherchez-les par leur nom.

Obtenir une vue

GET /v1/views/{viewId} · Portée : read:hierarchy:custom · Exige : aucun niveau sur une hiérarchie

Lit une vue : une vue de la personne, ou une vue partagée qu'elle peut utiliser. Toute autre vue répond 404.

curl -s "$BASE/v1/views/4" -H "Authorization: Bearer $TOKEN"

{ "id": 4, "name": "Colonnes de livraison", "mine": true, "shared": true, "editable": true,
  "columns": [ { "id": "c1", "type": "field", "field": "status" } ], "wrap": false }

Ce que l'API ne montre jamais

• Les tickets que la personne ne peut pas voir dans Jira. Les lignes placées par des règles que la personne ne peut pas voir sont laissées de côté, avec tout ce qui se trouve sous elles. Un ticket placé à la main que la personne ne peut pas voir apparaît comme une ligne restricted seulement là où il contient des lignes qu'elle peut voir. Cette ligne ne dit rien du ticket. La règle vaut pour tout le monde, administrateurs de l'application compris.
• Les champs des tickets. L'API renvoie l'identifiant des tickets. Lisez les tickets avec l'API REST de Jira et le même jeton.
• Les adresses courriel. Les personnes n'apparaissent que par leur identifiant de compte Atlassian.
• Les règles et leurs paramètres, pour les personnes qui n'ont pas Automatiser sur la hiérarchie.

Erreurs

Toutes les erreurs ont la même forme :

{ "error": { "status": 409, "code": "CONFLICT", "message": "row no longer exists" } }

Le message est toujours en anglais.

Les réponses 429, 502 et 503, ainsi que 409 IDEMPOTENCY_IN_PROGRESS, portent retryAfterSeconds dans le corps et un en-tête Retry-After, tous deux en secondes.

Un jeton qui n'a pas la portée exigée par une route est refusé par la passerelle d'Atlassian, avant l'application, avec 401 Unauthorized; scope does not match. Cette réponse n'a pas la forme ci-dessus.

Pagination

Les listes renvoient une page et un nextCursor. Renvoyez-le comme cursor pour obtenir la page suivante, jusqu'à ce que nextCursor vaille null. Les curseurs sont opaques : ne les construisez pas et ne les modifiez pas.

Si la ligne à partir de laquelle une page continue n'existe plus, la réponse est 409 CURSOR_STALE. Reprenez à la première page.

Limites de débit

Au-delà d'une limite, la réponse est 429 RATE_LIMITED avec retryAfterSeconds. Atlassian applique en plus ses propres limites de débit aux API REST des applications.

Chaque appel s'exécute aussi sur l'instance de l'application de votre site. Ce qu'il demande à Jira compte dans l'allocation horaire de points de l'API Jira de l'application sur votre site, que les pages de l'application partagent. Lire les lignes coûte à peu près autant qu'ouvrir la hiérarchie dans l'application. Pour limiter ce coût :

• lisez par grandes pages ;
• vérifiez la version d'une hiérarchie avec GET /v1/hierarchies/{id}, et ne relisez ses lignes que si elle a changé ;
• n'interrogez pas l'API plus souvent que nécessaire.

Idempotence

POST, PATCH et DELETE acceptent un en-tête facultatif Idempotency-Key : de 1 à 64 lettres, chiffres, - et _. Il rend une nouvelle tentative sans risque.

• La même clé avec la même demande dans les 24 heures renvoie la première réponse, avec l'en-tête Idempotent-Replayed: true. Rien n'est fait deux fois.
• La même clé avec une autre demande répond 422 IDEMPOTENCY_KEY_REUSED.
• La même clé pendant que le premier appel est encore en cours répond 409 IDEMPOTENCY_IN_PROGRESS avec Retry-After. Attendez, puis réessayez avec la même clé.
• Une première tentative qui a échoué avec 401, 429 ou une erreur 5xx avant de modifier quoi que ce soit ne laisse aucune trace : une nouvelle tentative avec la même clé l'exécute. Après un 401, réessayez une fois que la personne s'est connectée ou a autorisé l'application de nouveau.
• Une première tentative qui a échoué après avoir modifié quelque chose garde sa clé. Une nouvelle tentative avec cette clé répond 409 IDEMPOTENCY_IN_PROGRESS pendant la première minute, puis 409 IDEMPOTENCY_UNFINISHED : la première tentative s'est terminée sans réponse. Lisez la hiérarchie pour savoir si la modification a pris effet. Si ce n'est pas le cas, utilisez une nouvelle clé.
• Une réponse renvoyée est la première réponse que la personne a elle-même reçue pour cette demande, telle quelle. Elle n'est pas vérifiée de nouveau par rapport à ses accès.

Utilisez une nouvelle clé pour chaque modification que vous voulez faire, et la même clé pour réessayer cette modification. Sans clé, un POST réessayé peut faire son travail deux fois : une deuxième hiérarchie, ou des lignes ajoutées deux fois.

Gestion des versions

• Les chemins portent la version : /v1. Dans la v1, les changements ne font qu'ajouter : nouveaux champs, paramètres facultatifs et nouveaux points de terminaison. Ignorez les champs que vous ne connaissez pas.
• Un changement qui casserait les appelants crée /v2. La v1 continue de fonctionner au moins 12 mois après la sortie de la v2. Pendant ce temps, ses réponses portent les en-têtes Deprecation et Sunset.
• Les portées gardent leur sens. Une nouvelle portée oblige chaque intégration à redemander le consentement de ses utilisateurs.

Historique des versions

Prévu ensuite, sans ordre promis : les valeurs calculées des colonnes d'une vue, les clés des tickets dans les lignes, la modification des règles, les mémos et les éléments de planification, l'historique et les requêtes d'arbre.

Des questions sur l’application? Écrivez à info@plugincraft.ca.