Foto: Google Gemini · AI-generated
Die meisten Softwareentscheidungen sind umkehrbar. Sie wählen ein Framework, bereuen es und tauschen es aus. Die Kosten tragen Sie, und sie bleiben im eigenen Haus.
Eine API anzubieten ist etwas anderes. Sobald jemand sie einbindet, haben Sie einer fremden Partei etwas zugesagt — und Sie können diese Partei meist nicht erreichen, um neu zu verhandeln.
Dieses Ungleichgewicht sollte man verstanden haben, bevor man etwas veröffentlicht. Es verändert, was “fertig” bedeutet.
Sie sehen nicht, wer von Ihnen abhängt
Bei internem Code kennen Sie die Reichweite einer Änderung. Sie durchsuchen das Repository und finden jeden Aufrufer.
Bei einer angebotenen API funktioniert das nicht. Irgendwo sitzt ein Partner, der vor achtzehn Monaten angebunden hat, keine Tests gegen Sie geschrieben hat und seither nicht mehr an Ihren Dienst gedacht hat. Er liest Ihre Änderungshinweise nicht. Er erfährt von Ihrer Änderung, wenn seine Produktion stehenbleibt — und sein erster Anruf geht an Sie.
Wir haben CarLicence gebaut, eine Echtzeit-Plattform für die Verlängerung von Kfz-Zulassungen, die südafrikanische Unternehmen direkt einbinden: in eigene Websites, Apps, Kassensysteme und sogar Geldautomaten. Das Versprechen lautet, dass ein Partner in Stunden statt Wochen produktiv ist.
Überlegen Sie, was daraus folgt. Jeder dieser Partner hat unser Verhalten in sein eigenes Produkt eingebaut, vor seinen Kunden, unter seiner Marke. Ein Teil davon läuft auf Geräten, die niemand aktualisiert. Dass die Anbindung schnell geht, ist die leichtere Hälfte. Die schwerere ist, dass sie danach unbegrenzt dasselbe bedeuten muss.
Das Versprechen ist größer als die Endpunkte
Teams halten den Vertrag für die dokumentierte Anfrage und Antwort. Er ist deutlich weiter.
Sie sagen auch die Form Ihrer Fehler zu, denn jemand hat eine Behandlung geschrieben, die sich danach verzweigt. Die ungefähren Laufzeiten, denn jemand hat einen Timeout gesetzt. Die Reihenfolge, die Rundung, den Unterschied zwischen null und nicht vorhanden, die genaue Schreibweise eines Statuswerts, den jemand vergleicht. Alles Beobachtbare wird tragend, ob dokumentiert oder nicht.
Deshalb ist der Satz “wir haben nur ein internes Detail geändert” mit Vorsicht zu genießen. Was durch die Schnittstelle sichtbar ist, war nie intern.
Bauen Sie für den Neubau, den Sie noch nicht geplant haben
Die nützliche Disziplin: Behandeln Sie die Schnittstelle als älter und dauerhafter als das, was sie umsetzt. Nehmen Sie an, die Umsetzung wird ersetzt und die Schnittstelle nicht.
Das ist nicht theoretisch. Mobile ERP zeigt denselben Gedanken von der Nutzerseite: eine Lager-App für einen Sage-100-Add-on-Hersteller, die von Windows CE auf natives Android wechselte und weiterhin exakt so mit Sage 100 sprach wie zuvor. Die ganze Plattform darunter wurde getauscht. Der Vertrag nicht — genau deshalb konnten die Kunden ihre Hardware wechseln, ohne etwas an ihren Abläufen zu ändern.
Eine stabile Schnittstelle ist das, was die Schicht darunter austauschbar macht. Wer beides verflicht, kann nicht modernisieren, ohne eine abgestimmte Migration über alle Nutzer hinweg zu fahren — so wird aus einem Neubau eine fünfjährige Verhandlung.
Versionierung hält das Versprechen und lässt Sie trotzdem weitergehen
Nichts davon heißt, für immer einzufrieren. Es heißt, Änderungen zu planen statt zu überfallen.
Versionieren Sie die Schnittstelle, damit eine brechende Änderung eine neue Adresse ist und keine kaputte. Kündigen Sie Abkündigungen mit einem echten Datum an und halten Sie es. Lassen Sie die alte Fassung länger laufen, als es Ihnen sinnvoll erscheint, denn der Freigabezyklus anderer ist langsamer als Ihrer. Und wissen Sie, wer noch darauf ist — das erfordert Messen statt Vermuten.
Genau dort liegt die eigentliche Disziplin: Eine Version lässt sich nicht sicher abschalten, wenn man nicht sieht, wer sie nutzt. Nutzungsdaten je Partner sind deshalb keine Auswertung, sondern Voraussetzung für Veränderung.
Überwachung gehört zum Vertrag
Die letzte Pflicht ist, Probleme vor Ihren Partnern zu bemerken.
Wenn der Kunde eines Partners Ihre Verschlechterung zuerst entdeckt, haben Sie nicht nur einen Fehler ausgeliefert. Sie haben die Glaubwürdigkeit verbraucht, die die Anbindung überhaupt attraktiv gemacht hat. Verfügbarkeit, Antwortzeiten und Fehlerraten einer angebotenen API sind keine internen Kennzahlen. Sie sind das Versprechen selbst, gemessen.
Das ordentlich zu tun, ist unspektakulär und dauerhaft. Es unterscheidet aber eine Integration, die den nächsten Neubau überlebt, von einer, die stillschweigend zum Grund wird, warum der Neubau nicht stattfinden kann.
Wenn Sie eine Schnittstelle anbieten, auf der andere aufbauen, sprechen wir darüber.