16 — Travailler avec l'API

Presque tout ce que fait l'interface se fait aussi en HTTP : sauvegardes, rapports, vos propres outils.

Authentification

Créez un jeton d'accès (chapitre 10) et envoyez-le en en-tête à chaque requête :

TOKEN=votre-jeton
curl -H "Authorization: token $TOKEN" \
  https://forge.kabaforce.com/api/v1/user

Un jeton se limite aux permissions choisies à sa création : pas de droit d'écriture pour un travail en lecture seule.

Les points d'entrée les plus utilisés

Adresse de base : https://forge.kabaforce.com/api/v1

Point d'entrée	Ce qu'il renvoie
`/user`	Le compte propriétaire du jeton
`/user/repos?limit=50`	Les dépôts accessibles
`/repos/search?q=mot`	Recherche de dépôts
`/repos/{proprietaire}/{depot}`	Fiche du dépôt
`/repos/{proprietaire}/{depot}/contents/{chemin}`	Contenu d'un fichier ou dossier
`/repos/{proprietaire}/{depot}/branches`	Branches
`/repos/{proprietaire}/{depot}/commits?limit=10`	Derniers commits
`/repos/{proprietaire}/{depot}/issues?state=open`	Tickets ouverts
`/repos/{proprietaire}/{depot}/releases` · `/tags`	Versions et étiquettes

Les listes sont paginées : ?page=2&limit=50.

Lire un fichier

curl -H "Authorization: token $TOKEN" \
  "https://forge.kabaforce.com/api/v1/repos/proprietaire/projet/contents/docs"

Le champ content revient encodé en base64 ; demander le fichier brut est souvent plus simple :

curl -H "Authorization: token $TOKEN" \
  https://forge.kabaforce.com/proprietaire/projet/raw/branch/main/readme.md

Créer et mettre à jour des fichiers

curl -X POST -H "Authorization: token $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"content":"aGVsbG8=","message":"ajouter une note","branch":"main"}' \
  https://forge.kabaforce.com/api/v1/repos/proprietaire/projet/contents/notes.md

content est en base64. Pour mettre à jour un fichier existant, utilisez PUT et envoyez son sha actuel — c'est ce qui vous empêche d'écraser silencieusement le travail d'un autre.

Ouvrir un ticket

curl -X POST -H "Authorization: token $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title":"la page de connexion se décale sur mobile","body":"Étapes : ..."}' \
  https://forge.kabaforce.com/api/v1/repos/proprietaire/projet/issues

Codes d'erreur

Code	Signification
401	Jeton absent, erroné ou expiré
403	Jeton valide mais sans droit pour cette action
404	Mauvais chemin — ou dépôt privé hors de votre portée
409	Conflit : `sha` périmé lors d'une mise à jour
422	Corps mal formé (un ticket sans titre, par exemple)

Règles

N'écrivez pas le jeton dans le script ; lisez-le depuis une variable d'environnement.
Pour l'automatisation, créez un jeton dédié à portée étroite plutôt que d'utiliser le vôtre.
Si le travail ne fait que lire, préférez une clé de déploiement (chapitre 13).