Seminar Kroki – API, Kodierung, Formate und Diagrammoptionen

Diagramme zuverlässig über HTTP erzeugen

Kroki bündelt unterschiedliche Diagrammwerkzeuge hinter einer einheitlichen HTTP-Schnittstelle. Dadurch lässt sich ein Diagramm unabhängig von der jeweils verwendeten Sprache mit einem konsistenten Anfragemuster erzeugen. Das Seminar konzentriert sich vollständig auf diesen technischen Kern und verzichtet bewusst auf eine vertiefte Einführung in einzelne Diagrammnotationen.

Ein Seminartag ist für den klar abgegrenzten API-Schwerpunkt ausreichend. Im Mittelpunkt stehen nachvollziehbare Requests, kontrollierte Ausgabeformate und eine robuste Fehlerbehandlung. Die Lernstrecke beginnt mit einfachen Klartextanfragen und führt über JSON-Nutzdaten und kodierte GET-Adressen bis zu Diagrammoptionen, automatisierten Tests und wiederverwendbaren Aufrufmustern.

Inhaltsübersicht

• Aufbau der Kroki-Endpunkte und Auswahl des Diagrammtyps
• POST-Anfragen mit Klartext und JSON
• GET-Anfragen mit Deflate- und URL-sicherer Base64-Kodierung
• Content-Type, Accept-Header und Ausgabeformate
• Diagrammoptionen in URL, Header und JSON
• Fehlerantworten, Grenzfälle und Diagnose
• Skripte, Caching und reproduzierbare Aufrufe
• Automatisierte Funktions- und Regressionstests

Zielgruppe

Das Seminar richtet sich an Softwareentwickler, technische Redakteure, DevOps-Fachkräfte und Plattformadministratoren, die Kroki aus Anwendungen, Skripten, Dokumentationssystemen oder Build-Pipelines ansprechen. Die Inhalte sind auch für Teams geeignet, die eine bestehende Kroki-Integration vereinheitlichen oder belastbarer gestalten.

Voraussetzungen

Erforderlich sind Grundkenntnisse zu HTTP, Kommandozeile und strukturierten Daten. Praktische Erfahrung mit mindestens einer Skriptsprache ist hilfreich. Kenntnisse in PlantUML, Mermaid oder GraphViz sind nicht erforderlich, da einfache Beispieldiagramme bereitgestellt werden.

Lernstrecke Schritt für Schritt

1. Schritt 1: Anfragemodell und Endpunkte einordnen. Diagrammtyp, Ausgabeformat und Quelltext werden als voneinander getrennte Bestandteile betrachtet. Dadurch entsteht ein wiederverwendbares Modell für alle nachfolgenden Übungen.
2. Schritt 2: Einen ersten Klartext-Request senden. Ein kleines Graphdiagramm wird per POST an einen typbezogenen Endpunkt übertragen. Statuscode, Antwortheader und Bilddaten werden geprüft und dokumentiert.
3. Schritt 3: JSON-Anfragen strukturiert aufbauen. Diagrammquelle, Diagrammtyp, Ausgabeformat und Optionen werden in einem JSON-Objekt zusammengeführt. Pflichtfelder und typische Fehler bei der Serialisierung werden untersucht.
4. Schritt 4: Kodierte GET-Anfragen erzeugen. Der Diagrammtext wird als UTF-8 verarbeitet, mit Deflate komprimiert und URL-sicher in Base64 kodiert. Anschließend wird die resultierende Adresse erzeugt und wieder dekodiert.
5. Schritt 5: Content Negotiation gezielt einsetzen. Content-Type und Accept-Header werden so gesetzt, dass Quelle und gewünschtes Ergebnis eindeutig beschrieben sind. Varianten mit Formatangabe im Pfad werden verglichen.
6. Schritt 6: Ausgabeformate und Eignung bewerten. SVG, PNG, PDF und weitere verfügbare Formate werden hinsichtlich Skalierbarkeit, Einbettung, Druck, Barrierefreiheit und Nachbearbeitung eingeordnet.
7. Schritt 7: Diagrammoptionen übergeben. Optionen werden als Query-Parameter, HTTP-Header und JSON-Eigenschaften getestet. Die Priorität konkurrierender Angaben wird mit kontrollierten Beispielen nachvollzogen.
8. Schritt 8: Fehlerfälle reproduzierbar diagnostizieren. Unbekannte Diagrammtypen, fehlerhafte Syntax, ungültige Kodierung und ungeeignete Formate werden absichtlich ausgelöst. Aus Status, Headern und Antworttext entsteht ein Diagnoseablauf.
9. Schritt 9: Aufrufe in Skripte überführen. Wiederverwendbare Funktionen für Dateieingabe, Endpunktwahl, Zeitüberschreitung, Ausgabe und Rückgabecodes werden erstellt. Quellhashes dienen als Grundlage für lokales oder vorgelagertes Caching.
10. Schritt 10: Eine kleine API-Prüfsuite aufbauen. Positiv- und Negativfälle werden automatisiert ausgeführt. Die Prüfung kontrolliert Statuscode, Medientyp, Mindestgröße, deterministische Dateinamen und verständliche Fehlermeldungen.

Praxisaufgaben

• Ein Diagramm nacheinander als Klartext, JSON und kodierte GET-Anfrage rendern.
• Mehrere Ausgabeformate erzeugen und für Web, Dokumentation und Druck bewerten.
• Konfligierende Diagrammoptionen setzen und die wirksame Priorität nachweisen.
• Eine fehlerhafte Anfrage anhand eines festen Diagnoseprotokolls untersuchen.
• Ein wiederverwendbares Skript mit Zeitüberschreitung, Rückgabecode und Testfall erstellen.

Kompetenzziele

• Kroki-Endpunkte korrekt zusammensetzen und geeignete Request-Varianten auswählen.
• Diagrammquellen verlustfrei kodieren und wieder dekodieren.
• Header, Formate und Diagrammoptionen kontrolliert einsetzen.
• Fehlerursachen zwischen Transport, Kodierung, Syntax und Rendering unterscheiden.
• API-Aufrufe in belastbare Skripte und automatisierte Tests überführen.