Stack
Das Problem, das ich lösen wollte
Ich brauchte einen verlässlichen Weg, Business-Daten aus vielen chaotischen Quellen zu sammeln, zu bereinigen und zu strukturieren und sie anderen Tools in einer vorhersehbaren Form zu übergeben. Mein erster Instinkt war, wie bei den meisten Leuten, ein hübsches Dashboard zu bauen. Ich fing mit den Screens an. Das war der Fehler, der mich am meisten gelehrt hat.
Warum ich auf API-First umgestellt habe
Mittendrin merkte ich, dass jeder Konsument dieser Daten ein Programm war, kein Mensch, der auf Buttons klickt: eine Automation, ein Scraper, ein anderer Agent, ein zukünftiges Ich, das um Mitternacht ein Skript schreibt. Das UI war ein dünner Nachgedanke. Also baute ich das Ganze rund um eine dokumentierte API neu, mit dem Dashboard als nur einem Client dieser API statt als dem Produkt selbst.
- Jede Fähigkeit ist ein Endpunkt mit einem stabilen Vertrag, nicht ein Button, vergraben in einem Screen.
- Die API kommt mit einer OpenAPI-Spec, damit ein Agent sie entdecken und nutzen kann, ohne dass ich etwas erkläre.
- Antworten sind vorhersehbares JSON mit jedes Mal derselben Form, damit Konsumenten nie raten müssen.
Was sich änderte, als die API zuerst kam
In dem Moment, als die API das Produkt war, wurde alles dahinter einfacher. Automationen klinkten sich ein, ohne Screens abzukratzen. Testen wurde trivial, weil ich Endpunkte testete, nicht Klick-Flows. Und als ich einen KI Agent auf die OpenAPI-Spec ansetzte, konnte er BizCollect beim ersten Versuch korrekt nutzen, weil der Vertrag ihm genau sagte, was er senden muss und was er zurückbekommt. Das war der Aha-Moment: Ein Tool, das eine KI verstehen und ohne Händchenhalten bedienen kann, ist 2026 weit mehr wert als ein Tool, durch das sich nur ein Mensch navigieren kann.
Was ich anders machen würde
Ich würde die OpenAPI-Spec schreiben, bevor ich einen einzigen Endpunkt schreibe, und sie als Design-Dokument behandeln. Ich würde die API auch ab Tag eins versionieren, statt Versionierung später dranzuschrauben. Das Dashboard lässt sich immer neu generieren; ein kaputter API-Vertrag bricht jeden, der von dir abhängt, inklusive Agents, die du nie getroffen hast.
Gelernte Lektionen
- Entwirf die API vor dem UI. Die API ist das Produkt; das UI ist nur einer ihrer Clients.
- Liefere einen maschinenlesbaren Vertrag (OpenAPI), damit Agents dein Tool nutzen, ohne dass ein Mensch die Docs übersetzt.
- Vorhersehbare, identische Antwortformen schlagen clevere. Konsumenten sollten nie auf Überraschungen verzweigen müssen.
- In einer Agent-First-Welt ist "KI kann das unbeaufsichtigt bedienen" ein echtes Feature, kein Nice-to-have.