Das Handbuch zum API Life Cycle Mixer: Was gehört zu einer Single Source of Truth?

Nov 12, 2023

Von: Ariel DiFelice am 9. Juni 2023

Beim Barkeeper ist das Handbuch des Mixers eine vertrauenswürdige Informationsquelle. Diese Bücher können Hunderte von Rezepten für klassische Cocktails enthalten, von denen einige möglicherweise 100 Jahre alt sind, während andere möglicherweise erst kürzlich auf den Markt gekommen sind. Mixer-Handbücher können auch eine großartige Inspirationsquelle für neue, noch zu testende Rezepte für spannende Ergänzungen zum Angebot einer Bar oder eines Restaurants sein. Dieser Balanceakt, das Alte zu bewahren und gleichzeitig die Erforschung des Neuen zu fördern, kann eine wertvolle Lektion für die API-Entwicklung in der Softwarewelt sein. Die „Single Source of Truth“ einer API ist in vielerlei Hinsicht das Mixer-Handbuch des Softwareunternehmens. Dies gilt insbesondere dann, wenn der richtige Ansatz gewählt wird, um sicherzustellen, dass die Software funktionsfähig und leistungsfähig bleibt und Erlebnisse bietet, die Kunden begeistern und sie dazu bringen, wiederzukommen.

Während wir Mixologie und die Mixologen, die dieses Handwerk ausüben, vielleicht als relativ neue Begriffe betrachten, stammt die erste dokumentierte Verwendung des Wortes „Mixologe“ aus dem Jahr 1852 und „Mixologie“ folgte kurz darauf.

Wie ähnlich sind die Arbeit, Denkweisen und Leidenschaften von Mixologen und API-Entwicklern und -Designern? Schauen Sie sich diese Definition eines Mixologen an und zählen Sie selbst die Gemeinsamkeiten:

„Der Begriff ‚Mixologe‘ bezieht sich auf jemanden, der die Geschichte von Mixgetränken studiert, ein umfassendes Verständnis für die verwendeten Zutaten und Techniken besitzt und regelmäßig neue und innovative Mixgetränke kreiert … seine Berufsbezeichnung impliziert, dass er einen erheblichen Teil seiner Arbeit hinter sich hat.“ die Szenen, kreiert neue Craft-Cocktails und verleiht bestehenden Favoriten ihre eigene Note.“

Die besten API-Entwickler, Designer und Architekten der Welt sollten viele der oben genannten Punkte in ihrer eigenen Arbeit erkennen. Sie haben großen Respekt vor ihrem Handwerk und verfeinern es ständig weiter. Sie versuchen, den Geschmack und Gaumen ihrer Verbraucher zu verstehen. Sie berücksichtigen die Eingaben anderer Stakeholder, testen, iterieren und testen ihre Kreationen erneut, bevor sie diese APIs für die Produktion „bereitstellen“.

Wie Mixologen und Barkeeper (wenn man sie als zwei unterschiedliche Rollen betrachtet) sollte jeder Fachmann entlang des API-Lebenszyklus die Bedürfnisse von Verbrauchern, Kunden und dem Unternehmen verstehen – und dann seine APIs entsprechend entwerfen und entwickeln. Ein wesentlicher Bestandteil dieses Prozesses ist die kontinuierliche Validierung und Anpassung an die Marktanforderungen.

Auch geringfügige Änderungen an APIs können erhebliche nachgelagerte Auswirkungen haben. Und das Gleiche gilt für Änderungen an einem uralten Cocktailrezept, bei denen das Hinzufügen oder Entfernen eines einzigen Schusses von diesem oder jenem den Geschmack eines Getränks völlig verändern kann … und auch das Interesse der Leute daran.

Es gibt zwar keine „standardmäßige“ Änderungsrate für APIs, die man einplanen muss, Sie können jedoch damit rechnen, dass bei jeder neuen Softwareversion Änderungen erforderlich sind. Dies kann bedeuten, dass alle paar Wochen, jeden Monat oder sogar jeden Tag Änderungen vorgenommen werden (und getestet und validiert werden müssen), abhängig von Ihrem Veröffentlichungsrhythmus. Bei Bedarf können auch Ad-hoc-Änderungen vorgenommen werden.

Für Teams ist es wichtig sicherzustellen, dass diese Änderungen die Funktionalität oder Leistung einer API nicht beeinträchtigen. Um dies zu ermöglichen, nutzen Teams zunehmend API-Vertragstests, um eine Art Sicherheitsnetz bereitzustellen. Dies geschieht in Form von Tests, die Änderungen anhand eines „Vertrags“ validieren, der die ursprüngliche, vereinbarte und daher erforderliche Funktionalität einer API detailliert beschreibt.

Die Fähigkeit, die Auswirkungen von Änderungen an APIs vorherzusehen, kann von der Reife eines Engineering-Teams und seiner Fähigkeit zur Zusammenarbeit über Abteilungen, Zeitzonen und unterschiedliche technische Fachkenntnisse hinweg abhängen. Tools und Richtlinien, die Standardisierung und Zusammenarbeit fördern, können verhindern, dass bei Pannen negative nachgelagerte Auswirkungen übersehen oder ignoriert werden.

Ganz gleich, ob es darum geht, einer einzigen Quelle der Wahrheit für die aktuellste Version einer veröffentlichten API oder der neuesten Ausgabe eines Mixer-Handbuchs für bewährte Getränkerezepte vertrauen zu können, eine klare und prägnante Dokumentation ist dies Schlüssel. Es reicht aber auch nicht aus, dass diese Dokumentation einfach existiert.

Es scheint ein gesunder Menschenverstand zu sein – obwohl Sie wahrscheinlich irgendwo gearbeitet haben, wo das nicht der Fall war –, dass Ihre API-Dokumentation auch leicht zugänglich, verständlich und verwendbar sein muss. Die Sicherstellung all dieser Dinge führt zu einem reibungsloseren Onboarding und einer positiven Entwicklererfahrung und letztendlich zu einer breiteren Akzeptanz einer funktionalen, leistungsstarken API, die die Erwartungen erfüllt oder sogar übertrifft.

Die API-Dokumentation ist oft der erste Kontaktpunkt eines Entwicklers mit einer API. Es dient als Leitfaden und führt Entwickler durch die Funktionen, Endpunkte, Anforderungs-/Antwortmodelle und Fehlermeldungen der API. Es bietet außerdem Einblicke in die zugrunde liegende Geschäftslogik und die einzigartigen Eigenschaften einer API.

Eine gute API-Dokumentation folgt dem Prinzip einer Single Source of Truth, das heißt, sie sollte umfassend, aktuell und konsistent sein. Es sollte immer das tatsächliche Verhalten der API widerspiegeln, um das Rätselraten für Entwickler zu reduzieren und das Potenzial für Missverständnisse und Fehler zu minimieren.

So wie ein Mixologe sich auf ein detailliertes und genaues Cocktailrezept verlässt, um seinem Kunden ein angenehmes Erlebnis zu bieten, sind API-Entwickler auf eine gute Dokumentation angewiesen, um nützliche, wertschöpfende APIs und leistungsstarke Anwendungen zu erstellen und bereitzustellen.

Wie ein Mixologe, der die Zutaten eines Cocktails akribisch anpasst oder neue Cocktails kreiert, um den sich verändernden Geschmäckern der Kunden gerecht zu werden, müssen Entwickler ihre APIs ständig anpassen, um den sich ändernden Marktanforderungen, Geschäftsanforderungen und Industriestandards gerecht zu werden.

Dies wird durch eine wirkungsvolle Mischung aus Marktforschung, Zusammenarbeit, Einhaltung von Standards und Governance sowie sorgfältigen Tests erreicht. Da sich Technologien und Prozesse für Softwareentwicklung, Tests und Bereitstellung jedoch ständig weiterentwickeln, muss sich die Technologiebranche weiterbilden und ihre Praktiken verfeinern.

Mit einer Denkweise, die auf ständiges Lernen und kontinuierliche Verbesserung ausgerichtet ist und sich von einer zuverlässigen einzigen Quelle der Wahrheit leiten lässt, können Entwicklungsteams in jeder Version mit Zuversicht außergewöhnliche API-Erlebnisse bieten. Letztendlich besteht das Ziel darin, APIs zu entwickeln, die zuverlässig und einfach zu konsumieren sind und die individuellen Bedürfnisse des Augenblicks erfüllen – ähnlich wie das perfekte Getränk eines Mixologen.

Abgelegt unter: API, Anwendungsleistungsmanagement/-überwachung, Blogs, DevOps-Kultur, DevOps-Praxis, Doin' DevOps. Markiert mit: API, APIs, CI/CD, Entwickler, Entwicklung, Dokumentation, SDLC. Lebenszyklus, Software, Testen