REST API

Das Meldungen-Modul bietet eine vollständige REST API für die Integration mit externen Systemen und Automatisierung.

Überblick

RessourceEndpunktBeschreibung
Meldekreise/api/issue/tracker/Meldekreise verwalten
Kategorien/api/issue/category/Kategorien (Themen) verwalten
Meldungen/api/issue/issue/Meldungen verwalten

Authentifizierung

Alle API-Anfragen erfordern Authentifizierung:

Token-Authentifizierung (empfohlen):

curl -H "Authorization: Token DEIN_API_TOKEN" \
     https://deine-firma.myeliza.ch/api/issue/tracker/

Session-Authentifizierung: Für Browser-basierte Anfragen wird die Session-Authentifizierung automatisch verwendet.

💡 Tipp: API-Tokens kannst du in deinem Benutzerprofil unter “API-Zugang” erstellen.

Meldekreise (Tracker)

Alle Meldekreise auflisten

GET /api/issue/tracker/

Filter-Parameter:

  • state - Status (draft, approved, archived)
  • visibility - Sichtbarkeit (normal, protected, confidential)
  • public_form - Öffentliches Formular (true/false)
  • title - Suche im Titel

Beispiel:

curl -H "Authorization: Token TOKEN" \
     "https://firma.myeliza.ch/api/issue/tracker/?state=approved"

Meldekreis-Details abrufen

GET /api/issue/tracker/{id}/

Meldekreis erstellen

POST /api/issue/tracker/

Request-Body:

{
  "title": "Kundenreklamationen",
  "description": "Meldekreis für Kundenreklamationen",
  "state": "approved",
  "visibility": "normal",
  "public_form": false,
  "admin_ids": [1, 2],
  "team_ids": [3, 4, 5]
}

Meldekreis aktualisieren

PATCH /api/issue/tracker/{id}/

Meldekreis löschen

DELETE /api/issue/tracker/{id}/

Kategorien (Themen)

Kategorien sind Labels, die Meldungen innerhalb eines Meldekreises gruppieren.

Alle Kategorien auflisten

GET /api/issue/category/

Filter-Parameter:

  • tracker - Meldekreis-ID
  • title - Suche im Titel

Beispiel:

# Alle Kategorien eines Meldekreises
curl -H "Authorization: Token TOKEN" \
     "https://firma.myeliza.ch/api/issue/category/?tracker=1"

Kategorie-Details abrufen

GET /api/issue/category/{id}/

Kategorie erstellen

POST /api/issue/category/

Request-Body:

{
  "tracker_id": 1,
  "title": "Hardware-Fehler",
  "color": "red"
}

Felder:

FeldTypPflichtBeschreibung
tracker_idintegerJaID des Meldekreises
titlestringJaTitel der Kategorie
colorstringNeinMaterializeCSS Farbklasse

Kategorie aktualisieren

PATCH /api/issue/category/{id}/

Request-Body:

{
  "title": "Software-Fehler",
  "color": "blue"
}

Kategorie löschen

DELETE /api/issue/category/{id}/

Scoped Labels (Kategorien mit Scope)

Kategorien können als Scoped Labels angelegt werden, indem der Titel einen Doppelpunkt (:) enthält. Das Format ist Scope:Wert.

Beispiele:

{"tracker_id": 1, "title": "Priorität:Hoch", "color": "red"}
{"tracker_id": 1, "title": "Priorität:Mittel", "color": "orange"}
{"tracker_id": 1, "title": "Priorität:Niedrig", "color": "green"}
{"tracker_id": 1, "title": "Typ:Hardware", "color": "blue"}
{"tracker_id": 1, "title": "Typ:Software", "color": "purple"}

Darstellung in der UI:

Scoped Labels werden zweigeteilt dargestellt:

  • Linker Teil (Scope): Farbiger Hintergrund mit dem Scope-Namen
  • Rechter Teil (Wert): Weisser Hintergrund mit dem Wert
┌─────────────┬────────┐
│ Priorität   │  Hoch  │
└─────────────┴────────┘
   (farbig)    (weiss)

Vorteile von Scoped Labels:

  • Gruppierung zusammengehöriger Kategorien
  • Visuelle Unterscheidung von Scope und Wert
  • Konsistente Benennung (z.B. alle Prioritäten beginnen mit “Priorität:”)

Normale Labels:

Kategorien ohne : werden als einfache Labels dargestellt:

{"tracker_id": 1, "title": "Dringend", "color": "red"}

Verfügbare Farben (MaterializeCSS)

Die Farben werden als CSS-Klassen in der UI dargestellt.

Basis-Farben:

FarbeBeschreibungEmpfohlene Verwendung
redRotKritisch, Fehler
orangeOrangeWarnung
yellowGelbHinweis
greenGrünErledigt, OK
blueBlauInformation
purpleViolettSpezial
greyGrauNeutral
tealTürkisProzess
cyanCyanTechnik

Mit Helligkeitsstufen:

  • red lighten-2 - Helleres Rot
  • blue darken-1 - Dunkleres Blau
  • green accent-2 - Akzent-Grün

Stufen:

  • lighten-5 bis lighten-1 (heller)
  • darken-1 bis darken-4 (dunkler)
  • accent-1 bis accent-4 (Akzent)

Beispiele:

# Rote Kategorie für kritische Meldungen
curl -X POST -H "Authorization: Token TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"tracker_id": 1, "title": "Kritisch", "color": "red"}' \
     "https://firma.myeliza.ch/api/issue/category/"

# Hellblaue Kategorie für Informationen
curl -X POST -H "Authorization: Token TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"tracker_id": 1, "title": "Info", "color": "light-blue lighten-2"}' \
     "https://firma.myeliza.ch/api/issue/category/"

Meldungen (Issues)

Alle Meldungen auflisten

GET /api/issue/issue/

Filter-Parameter:

  • tracker - Meldekreis-ID
  • state - Status (new, pending, accepted, active, effectiveness_check, resolved, rejected)
  • archived - Archiviert (true/false)
  • assigned_user - Zuständiger Benutzer (ID)
  • classification - Klassifikation (official, confidential, secret)

Beispiel:

# Alle offenen Meldungen eines Meldekreises
curl -H "Authorization: Token TOKEN" \
     "https://firma.myeliza.ch/api/issue/issue/?tracker=1&state=active"

Meldung-Details abrufen

GET /api/issue/issue/{id}/

Meldung erstellen

POST /api/issue/issue/

Request-Body:

{
  "tracker_id": 1,
  "title": "Druckerproblem im 2. Stock",
  "description": "Der Drucker zeigt Papierstau an, obwohl kein Papier eingeklemmt ist.",
  "state": "new",
  "category_ids": [1, 2],
  "assigned_user_id": 5,
  "deadline": "2025-12-31"
}

Felder:

FeldTypPflichtBeschreibung
tracker_idintegerJaID des Meldekreises
titlestringJaTitel der Meldung
descriptionstringNeinBeschreibung
statestringNeinStatus (Standard: new)
category_idsarrayNeinKategorie-IDs
assigned_user_idintegerNeinZuständiger Benutzer
deadlinedateNeinFrist (YYYY-MM-DD)
contributor_idsarrayNeinMitwirkende (IDs)
process_idsarrayNeinVerknüpfte Prozesse (IDs)

Meldung aktualisieren

PATCH /api/issue/issue/{id}/

Beispiel: Status ändern

curl -X PATCH -H "Authorization: Token TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"state": "active"}' \
     "https://firma.myeliza.ch/api/issue/issue/42/"

Meldung löschen

DELETE /api/issue/issue/{id}/

Status-Workflow

Meldungen durchlaufen einen definierten Workflow:

new → pending → accepted → active → effectiveness_check → resolved
  ↓      ↓         ↓          ↓              ↓
rejected rejected rejected  rejected      rejected
StatusBeschreibung
newNeu erfasst
pendingIn Prüfung
acceptedAngenommen
activeIn Bearbeitung
effectiveness_checkWirksamkeitsprüfung
resolvedErledigt
rejectedAbgelehnt

Berechtigungen

Die API respektiert das ELIZA-Berechtigungssystem:

AktionErforderliche Berechtigung
Meldekreise lesenissues.view_tracker
Meldekreise erstellenissues.add_tracker
Meldekreise bearbeitenissues.change_tracker
Meldekreise löschenissues.delete_tracker
Kategorien lesenissues.view_issuecategory
Kategorien erstellenissues.add_issuecategory
Kategorien bearbeitenissues.change_issuecategory
Kategorien löschenissues.delete_issuecategory
Meldungen lesenissues.view_issue
Meldungen erstellenissues.add_issue
Meldungen bearbeitenissues.change_issue
Meldungen löschenissues.delete_issue

Zusätzlich werden objektspezifische Berechtigungen geprüft (z.B. Meldekreis-Sichtbarkeit).

Fehlerbehandlung

Die API gibt standardmässige HTTP-Statuscodes zurück:

CodeBedeutung
200Erfolg
201Erstellt
204Gelöscht (kein Inhalt)
400Ungültige Anfrage
401Nicht authentifiziert
403Keine Berechtigung
404Nicht gefunden
500Serverfehler

Fehler-Response:

{
  "detail": "Zugriff nicht erlaubt."
}

Validierungsfehler:

{
  "title": ["Dieses Feld ist erforderlich."],
  "tracker_id": ["Ungültiger pk \"999\" - Objekt existiert nicht."]
}

Beispiel-Workflows

Workflow 1: Meldung mit Kategorie erstellen

# 1. Verfügbare Kategorien abrufen
curl -H "Authorization: Token TOKEN" \
     "https://firma.myeliza.ch/api/issue/category/?tracker=1"

# 2. Meldung mit Kategorien erstellen
curl -X POST -H "Authorization: Token TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "tracker_id": 1,
       "title": "Produktionsfehler Charge 2024-001",
       "description": "Qualitätsmangel bei Charge 2024-001 festgestellt",
       "category_ids": [1, 3]
     }' \
     "https://firma.myeliza.ch/api/issue/issue/"

Workflow 2: Neue Kategorie anlegen und verwenden

# 1. Neue Kategorie erstellen
curl -X POST -H "Authorization: Token TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "tracker_id": 1,
       "title": "Lieferantenproblem",
       "color": "orange"
     }' \
     "https://firma.myeliza.ch/api/issue/category/"

# Response: {"id": 5, "tracker": 1, "title": "Lieferantenproblem", "color": "orange"}

# 2. Meldung mit neuer Kategorie erstellen
curl -X POST -H "Authorization: Token TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "tracker_id": 1,
       "title": "Verspätete Lieferung Lieferant XY",
       "category_ids": [5]
     }' \
     "https://firma.myeliza.ch/api/issue/issue/"

Nächste Schritte

api rest integration automation kategorien