Anzeige

REST-API

Datenaustausch
ETRM REST-API: Testergebnisse aus der CI direkt an die Anforderungen zurückschreiben
Beim Abspielen wird eine Verbindung zu YouTube (Google) hergestellt. Mehr dazu in der Datenschutzerklärung · Auf YouTube ansehen

Die REST-API v1 öffnet den ETRM für eigene Programme: Testergebnisse aus der Testautomatisierung zurückschreiben, Anforderungen in ein anderes Werkzeug spiegeln, vor einem Release eine Baseline anlegen oder Kennzahlen in einen Projektbericht übernehmen.

Voraussetzung: Abonnement

Die REST-API setzt das Zusatz-Abo ETRM API voraus, das Sie zu einem eigenen aktiven Abonnement Single oder Team buchen. Es gilt für Ihren Account; Mitglieder einer Team-Gruppe buchen es zu einem eigenen Single-Abo. Ohne beide Abos antwortet die API mit dem Status 403 und dem Fehlercode subscription_required. Ihre Schlüssel bleiben dabei erhalten und gelten wieder, sobald die Abos aktiv sind.

Zugangsschlüssel anlegen

  1. Öffnen Sie Account → API-Zugang.
  2. Geben Sie einen Namen an, zum Beispiel „Testautomatisierung“, und entscheiden Sie, ob der Schlüssel schreiben darf.
  3. Kopieren Sie den angezeigten Schlüssel sofort. Er wird nur dieses eine Mal angezeigt; der ETRM speichert nicht den Schlüssel selbst, sondern nur einen Prüfwert (Hash).

Ein Schlüssel handelt mit Ihren Rechten in den Gruppen: Er sieht dieselben Projekte und darf dasselbe wie Sie in der Oberfläche. Ohne Schreibrecht kann er nur lesen. Nicht mehr benötigte oder versehentlich weitergegebene Schlüssel widerrufen Sie auf derselben Seite; sie verlieren sofort den Zugriff.

Was die API kann

Bereich lesen schreiben
Projekte Liste, Konfiguration (Typen, Attribute mit Werten, Link-Typen), Module –
Artefakte Liste mit Filtern (Typ, Modul, Schlagwort, Volltext, Attribute, geändert seit), einzeln mit Links anlegen (auch im Modul unter einer Überschrift), ändern, in den Papierkorb
Schlagworte Liste des Projekts, Schlagworte eines Artefakts, Filter in der Artefaktliste an Artefakte hängen (auch an mehrere auf einmal), abnehmen, ungenutzte löschen (nur Gruppenadmins; Baselines und Verlauf behalten die Namen)
Links Liste mit Filtern (Typ, Artefakt, verdächtig) anlegen, löschen, Verdacht quittieren
Module Gliederung mit Nummern, Überschrift und Position vorhandene Artefakte einfügen, verschieben, aus dem Modul entfernen
Baselines Liste, Stand, Vergleich mit einer anderen Baseline oder dem aktuellen Stand anlegen
Kennzahlen wie im Dashboard –

Alle Änderungen über die API laufen durch dieselben Prüfungen wie in der Oberfläche: Pflichtattribute, erlaubte Werte und Link-Typen, Historie und verdächtige Links. Beim Ändern geben Sie die Version (rev) mit, die Sie gelesen haben; hat jemand inzwischen geändert, antwortet die API mit dem Status 409 und dem aktuellen Stand, statt fremde Änderungen zu überschreiben. Für die Gliederung eines Moduls gilt dasselbe mit dem Strukturstand, den die API als ETag liefert und den Sie mit If-Match zurückschicken.

Bei sehr vielen Anfragen in kurzer Zeit antwortet die API mit dem Status 429 und dem Fehlercode rate_limited. Die Kopfzeile Retry-After nennt die Sekunden, nach denen Sie es erneut versuchen können; verteilen Sie automatisierte Abrufe daher gleichmäßig.

Beispiel

curl -H "Authorization: Bearer etrm_…" \
  "<Adresse des ETRM>/api/v1/projects/<id>/artifacts/?type=systemanforderung&attr.status=freigegeben"

Die Projekt-ID ist dieselbe wie in der Adresszeile der Projektübersicht, Artefakte werden über ihre Nummer angesprochen (#12 → 12).

Die vollständige Beschreibung aller Endpunkte mit Beispielen und der genauen Adresse finden Sie in der API-Dokumentation.



Zurück zur Übersicht