September 2026

Pathly als API, und ein Terraform-Provider

APIHinter den Kulissen

Infrastruktur in Dateien beschreiben, Überwachung von Hand anlegen: das sind zwei Wahrheiten, die auseinanderlaufen. Sie lässt sich jetzt als Code schreiben, per API und Terraform-Provider.

Der veröffentlichte Vertrag ist der laufende

Die API liefert ihren eigenen OpenAPI-Vertrag aus, ohne Authentifizierung, unter einer öffentlichen Adresse. Dieses Dokument wird nicht neben dem Code geschrieben: es entsteht aus der Tabelle, die die Routen deklariert — genau jener, die bei jedem Aufruf über den nötigen Geltungsbereich entscheidet. Eine Route, die dort fehlt, startet nicht. Die Entwicklerseite liest diesen Vertrag beim Rendern, sodass ein entfernter Endpunkt von selbst aus der Dokumentation verschwindet. Handkopierte Dokumentation lügt immer, die Frage ist nur, seit wann.

• Die Entwicklerseite
• Der OpenAPI-Vertrag, als JSON

Enge Geltungsbereiche, und vier Absagen

Ein Schlüssel trägt Geltungsbereiche der Form Ressource und Aktion: Szenarien lesen, schreiben, eine Ausführung auslösen, einen Vorfall schließen. Schreiben schließt Lesen ein, denn ein Werkzeug liest immer erneut, was es gerade geschrieben hat. Auslösen bleibt vom Lesen getrennt, denn eine Ausführung verbraucht Kontingent und ist keine Abfrage.

Vier Handlungen bleiben einem Schlüssel verwehrt, aus Entscheidung und nicht aus Versehen. Schlüssel ausstellen oder widerrufen, denn ein Schlüssel, der das kann, hebt die Geltungsbereiche aller anderen auf. Mitglieder einladen, denn es läuft auf einem Umweg aufs Gleiche hinaus: das neue Konto stellt beliebige Schlüssel aus. Tarif wechseln oder die Abrechnung anfassen, denn ein CI-Token darf keine Ausgaben verursachen. Die Organisation exportieren, denn der Export enthält Mitglieder, also personenbezogene Daten.

• Einen Schlüssel ausstellen und Geltungsbereiche wählen

Was beim Lesen nie zurückkommt

Ein Authentifizierungspasswort, die Adresse eines Webhooks, die Schritte eines Browser-Ablaufs: diese Werte werden geschrieben und kommen nicht zurück. Stattdessen liefert die API eine Prüfsumme aus zwölf Zeichen, die sich ändert, sobald sich der Wert ändert. Das genügt, damit ein Werkzeug erkennt, dass eine Ressource anderswo geändert wurde, und ist viel zu wenig, um ihren Inhalt zu rekonstruieren. Terraform nutzt genau das: ein in der Konsole von Hand geändertes Webhook-Ziel taucht im nächsten Plan auf, ohne dass die Adresse je in eine Statusdatei geschrieben wird.

Was ein automatisiertes Werkzeug von einer API erwartet

• Cursor-Paginierung statt Seitenzahlen: eine während des Durchlaufs erstellte Ressource würde die Seiten verschieben, und der Client läse eine Zeile doppelt oder übersprünge eine.
• Ein Retry-After-Header beim Überschreiten des Limits: ohne ihn wiederholt ein automatisierter Client blind und bleibt in seiner eigenen Schleife.
• Ein Idempotenzschlüssel, der vierundzwanzig Stunden wiederholt wird: eine nach einem Netzausfall neu gestartete Pipeline erzeugt keine Dubletten.
• Eine Kennung, die zu einer anderen Organisation gehört, antwortet mit 404, nie mit 403: „verboten“ würde ihre Existenz bestätigen.

Der Provider

Vier Ressourcen — ein Szenario, ein Wartungsfenster, ein Webhook, ein Verfügbarkeitsziel — und eine Datenquelle, die den Bestand erneut liest, genug, um ein in der Konsole von Hand angelegtes und im Code fehlendes Szenario zu erkennen. API-Schlüssel und Mitglieder fehlen, aus dem bereits genannten Grund: eine Terraform-Datei, die einen Eigentümer einlädt, ist eine Rechteausweitung über Umwege.

Zwei Verhaltensweisen zählen mehr als die Liste der Ressourcen. Nach einem Apply muss ein Plan leer sein: sonst schlägt das Werkzeug bei jedem Durchlauf eine Änderung vor, und niemand liest seine Pläne mehr. Und Adresse, Intervall oder Latenzschwelle eines Szenarios zu ändern muss es an Ort und Stelle aktualisieren, nie zerstören und neu anlegen — ein neu angelegtes Szenario verliert seine Historie und seine Vorfälle, also alles, wofür es überwacht wurde. Diese beiden Punkte verlangten auf API-Seite, dass alles Schreibbare identisch zurückgelesen werden kann. Das ist die unsichtbarste Arbeit am Provider und die, die über seine Brauchbarkeit entscheidet.

Einen bestehenden Bestand übernehmen

Niemand baut seine Überwachung von Grund auf neu, um zu Code zu wechseln. Jede Ressource lässt sich über ihre Kennung importieren: das letztes Jahr in der Konsole angelegte Szenario gelangt unverändert in den Terraform-Status, und der nächste Plan zeigt den Unterschied zwischen dem, was es ist, und dem, was die Datei beschreibt. Das ist der einzige ehrliche Weg zu migrieren, und auch der, der eine Rückkehr erlaubt.

Wo er steht

Der Provider ist auf der öffentlichen Terraform-Registry veröffentlicht, mit Dokumentation und Beispielen: eine Version in einem required_providers-Block genügt jetzt zur Installation, ohne lokalen Spiegel und ohne Bauen aus den Quellen. Die Nummerierung bleibt bei 0.x, und das heißt etwas Bestimmtes: bestehende Ressourcen bewegen sich nicht ohne Grund, doch wir behalten uns vor, vor 1.0 ein Schema anzupassen. Die API wartet nicht auf den Provider: ein Schlüssel, eine Adresse und die Entwicklerdokumentation genügen, um dasselbe aus jeder Sprache zu steuern.