Anzeige

REST-API v1

Lesen und schreiben Sie Artefakte, Links, Module und Baselines aus eigenen Programmen, Skripten oder Ihrer CI-Pipeline.

Anmeldung

Die REST-API setzt das Zusatz-Abo ETRM API zu einem eigenen Single- oder Team-Abo voraus. Ohne beide Abos antwortet sie mit dem Status 403 und dem Fehlercode subscription_required.

Legen Sie unter Profil, API-Zugang einen Zugangsschlüssel an und senden Sie ihn bei jeder Anfrage im Kopf Authorization mit. Der Schlüssel handelt mit Ihren Rechten in den Gruppen. Schlüssel ohne Schreibrecht können nur lesen.

curl -H "Authorization: Bearer etrm_…" https://engineering-toolbox.com/etrm/api/v1/

Grundlagen

  • Basisadresse: https://engineering-toolbox.com/etrm/api/v1/. Anfragen und Antworten sind JSON (UTF-8).
  • Projekte haben dieselbe ID wie in den Adressen der Oberfläche. Artefakte werden über ihre Nummer angesprochen (#12 wird zu 12).
  • Rechte wie in der Oberfläche: Lesen braucht die Rolle READ, Anlegen, Ändern und Löschen die Rolle EDIT.
  • Listen sind seitenweise: Parameter limit (höchstens 500, Vorgabe 100) und offset; die Antwort enthält count und next_offset.
  • Texte sind eingeschränktes Rich Text (HTML). Der Server bereinigt sie wie beim Speichern in der Oberfläche.
  • Jede Änderung erzeugt eine neue Version in der Historie und markiert Links wie in der Oberfläche als verdächtig.

Projekte

GETprojects/Ihre Projekte mit Rolle (archivierte mit ?archived=1).
GETprojects/<id>/Projekt mit Konfiguration: Artefakttypen, Attribute mit erlaubten Werten, Link-Typen, Module.
GETprojects/<id>/metrics/Kennzahlen wie im Dashboard: Umfang, Abdeckung, verdächtige Links, Volatilität, Formulierungshinweise.

Artefakte

GETprojects/<id>/artifacts/Liste. Filter: type (mehrfach), module, tag (mehrfach, eines genügt), q (Volltext), changed_since (ISO 8601), attr.<schlüssel>=<wert>, deleted=1 (auch Papierkorb).
POSTprojects/<id>/artifacts/Anlegen. Optional mit tags (Liste), module, parent (Nummer einer Überschrift im Modul) und position.
GETprojects/<id>/artifacts/<nr>/Ein Artefakt mit Modulen und Links.
PATCHprojects/<id>/artifacts/<nr>/Ändern von title, text, type, attributes und tags (ersetzt die ganze Liste). Pflicht ist rev (aktueller Stand); hat sich das Artefakt inzwischen geändert, kommt 409 mit dem aktuellen Stand. In attributes entfernt null einen Wert.
DELETEprojects/<id>/artifacts/<nr>/In den Papierkorb (wiederherstellbar in der Oberfläche).

Beispiel: Systemanforderung anlegen

curl -X POST -H "Authorization: Bearer etrm_…" -H "Content-Type: application/json" \
  -d '{"type": "systemanforderung", "title": "Zellspannung messen",
       "text": "<p>Das BMS muss jede Zellspannung mit ±2 mV messen.</p>",
       "attributes": {"status": "entwurf", "prioritaet": "muss"}, "module": 3, "parent": 12}' \
  https://engineering-toolbox.com/etrm/api/v1/projects/<id>/artifacts/

Antwort (gekürzt)

{"number": 131, "id": "#131", "uid": "6f1c…", "type": "systemanforderung", "title": "Zellspannung messen",
 "text": "<p>…</p>", "attributes": {"status": "entwurf", "prioritaet": "muss"}, "tags": [], "rev": 1,
 "deleted": false, "quality": [], "url": "…/artifacts/131/"}

Das Feld quality enthält die Hinweise der Formulierungsprüfung (z. B. vage Begriffe oder offene Punkte).

Schlagworte

GETprojects/<id>/tags/Schlagworte des Projekts mit color, active und count (Artefakte außerhalb des Papierkorbs).
GETprojects/<id>/artifacts/<nr>/tags/Schlagworte eines Artefakts.
POSTprojects/<id>/artifacts/<nr>/tags/Schlagworte anhängen: tags (Liste von Namen). Unbekannte Namen werden im Projekt angelegt. added nennt, was neu dazukam.
DELETEprojects/<id>/artifacts/<nr>/tags/<name>/Ein Schlagwort abnehmen. Es bleibt im Projekt erhalten; removed ist null, wenn es nicht anhing.
POSTprojects/<id>/tags/<name>/artifacts/Sammelaktion wie in der Tabelle: ein Schlagwort an mehrere Artefakte hängen (numbers, höchstens 500).
DELETEprojects/<id>/tags/<name>/Ein ungenutztes Schlagwort aus dem Projekt löschen (nur Gruppenadmins). Antwort: name und deleted. Hängt es noch an Artefakten (auch im Papierkorb), kommt 409 tag_in_use mit count.

Es gelten dieselben Regeln wie in der Oberfläche: Groß- und Kleinschreibung spielt keine Rolle, Namen haben höchstens 50 Zeichen und kein Komma. Anhängen und Abnehmen lassen sich gefahrlos wiederholen, ändern rev nicht und erscheinen im Verlauf des Artefakts. Namen mit Sonderzeichen in der Adresse URL-kodieren.

Löschen lassen sich nur ungenutzte Schlagworte. Baselines und Verlauf behalten die Namen, frühere Stände bleiben dadurch unverändert.

Beispiel: zwei Schlagworte anhängen

curl -X POST -H "Authorization: Bearer etrm_…" -H "Content-Type: application/json" \
  -d '{"tags": ["Sicherheit", "ASIL B"]}' \
  https://engineering-toolbox.com/etrm/api/v1/projects/<id>/artifacts/131/tags/

Antwort (gekürzt)

{"number": 131, "tags": ["ASIL B", "Sicherheit"], "added": ["ASIL B"]}

Module

GETprojects/<id>/modules/Liste der Module mit structure_rev.
GETprojects/<id>/modules/<modul>/Gliederung in Dokumentreihenfolge mit Nummer (1.2, 1.2-3), Tiefe, Artefakt, parent (Nummer der Überschrift) und position. Kopfzeile ETag enthält den Strukturstand.
POSTprojects/<id>/modules/<modul>/artifacts/Vorhandenes Artefakt einfügen: artifact (Nummer), optional parent und position. Ohne Angabe ans Ende der obersten Ebene.
GETprojects/<id>/modules/<modul>/artifacts/<nr>/Stelle eines Artefakts im Modul.
PATCHprojects/<id>/modules/<modul>/artifacts/<nr>/Überschrift (parent, null für die oberste Ebene) und/oder position ändern. Untergeordnete Artefakte wandern mit.
DELETEprojects/<id>/modules/<modul>/artifacts/<nr>/Aus dem Modul entfernen. Das Artefakt bleibt mit Nummer, UID, Historie und Links im Projekt; untergeordnete Artefakte rücken an seine Stelle.

position zählt ab 0 innerhalb der Ebene, Artefakte im Papierkorb zählen nicht mit. Ein Artefakt steht in einem Modul höchstens einmal, in mehreren Modulen ist es dasselbe Artefakt.

Gleichzeitige Änderungen: Senden Sie den gelesenen ETag im Kopf If-Match (oder als structure_rev im Inhalt) mit. Hat sich die Gliederung inzwischen geändert, auch in der Oberfläche, kommt 409 mit der aktuellen Gliederung in current. Ohne Angabe wird nicht geprüft.

Beispiel: Artefakt unter Überschrift #12 an die erste Stelle einfügen

curl -X POST -H "Authorization: Bearer etrm_…" -H "Content-Type: application/json" -H 'If-Match: "s-7"' \
  -d '{"artifact": 131, "parent": 12, "position": 0}' \
  https://engineering-toolbox.com/etrm/api/v1/projects/<id>/modules/3/artifacts/

Baselines

GETprojects/<id>/baselines/Liste.
POSTprojects/<id>/baselines/Neuen Stand anlegen: name, optional note und module.
GETprojects/<id>/baselines/<b>/Eine Baseline; mit ?payload=1 der vollständige, unveränderliche Stand.
GETprojects/<id>/baselines/<b>/compare/Unterschiede zum aktuellen Stand oder mit ?with=<b> zu einer anderen Baseline: neu, entfernt, geändert, verschoben, Links.

Fehler

Fehler kommen als JSON mit error (Kennung) und message (Text), bei ungültigen Angaben zusätzlich details je Feld.

400ungültige Angaben (validation, invalid_json, invalid_parameter)
401Token fehlt, ist unbekannt oder widerrufen
403Rolle reicht nicht, Token darf nur lesen oder kein aktives Zusatz-Abo ETRM API (subscription_required)
404nicht gefunden (auch Projekte, in denen Sie kein Mitglied sind)
405Methode nicht erlaubt
409Konflikt: Das Artefakt oder die Modulgliederung wurde inzwischen geändert (Antwort enthält current), das Artefakt liegt im Papierkorb oder steht schon im Modul (already_bound)
{"error": "validation", "message": "Die Angaben sind nicht gültig.", "details": {"prioritaet": ["Pflichtfeld."]}}