16 — Mit der API arbeiten

Fast alles, was in der Oberfläche geht, geht auch über HTTP: Sicherungen, Auswertungen, eigene Werkzeuge.

Authentifizierung

Erzeugen Sie ein Zugriffstoken (Kapitel 10) und schicken Sie es als Header mit:

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

Ein Token kann nur, was Sie beim Erzeugen erlaubt haben: für eine reine Leseaufgabe kein Schreibrecht vergeben.

Die meistgenutzten Endpunkte

Basisadresse: https://forge.kabaforce.com/api/v1

Endpunkt	Was er liefert
`/user`	Das Konto, dem das Token gehört
`/user/repos?limit=50`	Erreichbare Repositories
`/repos/search?q=wort`	Repository-Suche
`/repos/{besitzer}/{repo}`	Stammdaten des Repositories
`/repos/{besitzer}/{repo}/contents/{pfad}`	Datei- oder Ordnerinhalt
`/repos/{besitzer}/{repo}/branches`	Branches
`/repos/{besitzer}/{repo}/commits?limit=10`	Letzte Commits
`/repos/{besitzer}/{repo}/issues?state=open`	Offene Issues
`/repos/{besitzer}/{repo}/releases` · `/tags`	Releases und Tags

Listen sind seitenweise: ?page=2&limit=50.

Eine Datei lesen

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

Das Feld content kommt base64-kodiert zurück; die rohe Datei zu holen ist meist einfacher:

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

Dateien anlegen und ändern

curl -X POST -H "Authorization: token $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"content":"aGVsbG8=","message":"Notiz ergänzt","branch":"main"}' \
  https://forge.kabaforce.com/api/v1/repos/besitzer/projekt/contents/notizen.md

content ist base64. Zum Ändern einer vorhandenen Datei nehmen Sie PUT und schicken deren aktuelle sha mit — das verhindert, dass Sie fremde Änderungen still überschreiben.

Ein Issue eröffnen

curl -X POST -H "Authorization: token $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title":"Anmeldeseite verrutscht auf dem Handy","body":"Schritte: ..."}' \
  https://forge.kabaforce.com/api/v1/repos/besitzer/projekt/issues

Fehlercodes

Code	Bedeutung
401	Kein, falsches oder abgelaufenes Token
403	Token gültig, aber ohne Recht für diese Aktion
404	Falscher Pfad — oder ein privates Repository ohne Zugriff
409	Konflikt: veralteter `sha` beim Ändern
422	Fehlerhafter Rumpf (etwa ein Issue ohne Titel)

Regeln

Das Token nicht ins Skript schreiben, sondern aus einer Umgebungsvariablen lesen.
Für Automatisierung ein eigenes, eng geschnittenes Token statt Ihres allgemeinen.
Wenn der Job nur liest, ist ein Deploy-Key die bessere Wahl (Kapitel 13).