API-Design-Bewertungen sind tot. Es lebe API-Design-Rezensionen!

Jul 28, 2023

InfoQ-Homepage-Artikel API-Design-Bewertungen sind tot. Es lebe API-Design-Rezensionen!

22. Mai 2023 8 Minuten Lesezeit

von

Jason Harmon

rezensiert von

Thomas Betts

Bei der Entwicklung von APIs im großen Maßstab ist es erforderlich, bewusste Anstrengungen zu unternehmen, um Konsistenz zu schaffen. Der Hauptunterschied zwischen einer Reihe von APIs und etwas, das sich wie eine echte Plattform anfühlt, ist die Konsistenz. In diesem Fall bedeutet Konsistenz einfach, dass bei der Verwendung mehrerer APIs Faktoren wie Namenskonventionen, Interaktionsmuster wie Paging und Authentifizierungsmechanismen allgemein Standard sind.

Traditionell traumatisieren Prüfausschüsse API-Entwickler mit Entdeckungen, die zu Verzögerungen führen, wenn die Entwicklung als abgeschlossen angenommen wird. Schlimmer noch, das Design durch ein Komitee kann die Oberhand gewinnen, den Fortschritt aufhalten oder Entwickler dazu ermutigen, Wege zu finden, den Prozess zu umgehen, um den Schmerz ganz zu vermeiden.

Um eine moderne Plattform wirklich zu erschließen, ist die Aktivierung durch dezentrale Governance ein viel skalierbarerer und ansprechenderer Ansatz. Dies bedeutet einfach, dass jede Domäne oder jeder Funktionsbereich über einen Fachexperten verfügt, der in den Standards und der Gesamtarchitektur geschult wurde, um als kompetenter Leitfaden für API-Entwickler zu dienen.

Identitäten schützen. Sichere digitale Dienste. Ermöglichen Sie einen skalierbaren und sicheren Benutzerzugriff auf Web- und mobile Anwendungen. Kostenlos testen.

Noch wichtiger ist, dass durch die Einigung auf das API-Design vor Abschluss des Großteils der Entwicklung weitgehend Entdeckungen in letzter Minute vermieden werden können, die die Lieferzeiten gefährden (oft als Design-First-Ansatz bezeichnet). Die Verwendung eines Spezifikationsformats wie OpenAPI (der De-facto-Standard für HTTP/„REST“-APIs) bietet die Möglichkeit, vor jeder Entwicklung eine API zu definieren, was eine viel frühere Ausrichtung und Identifizierung von Problemen ermöglicht.

Schauen wir uns vor diesem Hintergrund genauer an, wie man API-Designüberprüfungen durchführt und wie man Prozesse entwickelt und die Organisation darauf vorbereitet, lange Zeitpläne und mangelndes Engagement der Entwickler zu vermeiden.

Hier einige wichtige Voraussetzungen für einen reibungslosen Ablauf:

Die Verwendung von APIs ist eine sehr destillierte Erfahrung, und daher ist der Einfluss der Sprache unverhältnismäßig höher als in den meisten anderen Designbereichen. Jedes Teammitglied hat möglicherweise eine etwas andere Art und Weise, verschiedene Begriffe zu definieren und zu beschreiben, was sich in Verwirrung und verminderter Produktivität für API-Teams äußert.

Während API-Portale/Dokumentation für ein großartiges Entwicklererlebnis unerlässlich sind, sollten gut gestaltete APIs den Großteil der Geschichte erzählen, ohne dass man viel darüber nachdenken muss. Wenn dem Verbraucher Begriffe bekannt sind und Interaktionsmuster offensichtlich sind, kann das Erlebnis schnell und schmerzlos erfolgen. Konsistenz ist der Hauptunterschied in der Erfahrung zwischen einer Reihe von APIs und etwas, das sich wie eine einzige Plattform anfühlt.

Beginnen Sie bei der Einrichtung Ihres API-Programms und Governance-Prozesses mit einer gemeinsamen Sprache. Auch wenn es auf den ersten Blick unmöglich erscheint, ist die Definition eines kundenorientierten gemeinsamen Vokabulars/einer gemeinsamen Grammatik für Ihre Plattform unerlässlich und ein allgemeiner Beschleuniger für ein Unternehmen. Viele Begriffe können innerhalb eines Unternehmens unterschiedliche Bedeutungen haben, und was die Sache noch schlimmer macht, sind diese oft Begriffe, die der Endverbraucher nicht einmal erkennen würde.

Wenn Sie diese Hausaufgaben im Voraus erledigen, vermeiden Sie Konflikte über die Benennung während des API-Entwurfs. Arbeiten Sie jeden Bereich mit relevanten Stakeholdern durch, um eine gemeinsame Terminologie zu definieren und eine breite Verfügbarkeit und Bekanntheit für API-Designer sicherzustellen. Und wenn Sie sich für eine interne Standardisierung der Begriffe entschieden haben, vergessen Sie nicht zu prüfen, ob diese auch Ihren externen Anforderungen entspricht. Durch die Verwendung der Kundensprache und eine kundenzentrierte Sicht auf die API-Entwicklung können Teams vermeiden, ihre Kunden mit unbekannten Fachbegriffen zu verwirren. Stellen Sie daher sicher, dass Ihr internes und Ihr externes Verständnis synchronisiert sind.

Wenn API-Konsumenten auf Modelle oder Parameter stoßen, die zwischen APIs variieren, kann dies ein verwirrender, frustrierender und zeitaufwändiger Prozess sein. Wenn Sie beispielsweise eine API verwenden, die auf Kontaktinformationen verweist, und die nächste API auf derselben Plattform ein völlig anderes Modell verwendet, müssen Verbraucher diese Unterschiede häufig beheben. Schlimmer noch, es können systemische Unterschiede im Umgang mit diesen Daten entstehen, die zu funktionalen Unterschieden führen.

Identifizieren Sie so früh wie möglich gemeinsame Komponenten (Modelle, Parameter, Header usw.) und die Systeme, die sie unterstützen. Durch die Verknüpfung mit gemeinsam genutzten Komponenten in API-Definitionen wird sichergestellt, dass zukünftige Änderungen an diesen Komponenten einfacher auf der gesamten Plattform eingeführt werden können und eine übermäßige kognitive Belastung für API-Konsumenten verringert wird.

Je mehr gemeinsame Komponenten Sie haben, desto größer sind die Chancen auf mehr Konsistenz, Wiederverwendbarkeit, weitere Möglichkeiten zur Zusammenarbeit und höhere Effizienz. Wir alle in der Entwicklerwelt lieben die „DRY-Methode“ (Don't Repeat Yourself) und je mehr gemeinsame Komponenten vorhanden sind, desto einfacher ist es, Innovationen zu entwickeln, ohne immer wieder dasselbe von Grund auf neu erstellen zu müssen. Durch gemeinsam genutzte Komponenten kann Ihr Team außerdem schnell skalieren und neue Entwickler oder Stakeholder außerhalb des API-Teams problemlos schulen.

Für die überwiegende Mehrheit der einfachen Namenskonventionen, Interaktionsmuster und Authentifizierungsmechanismen kann eine Automatisierung mit Styleguides bereitgestellt werden, um Inkonsistenzen so früh wie möglich zu erkennen.

Die ersten Styleguides wurden zwischen 2013 und 2015 entwickelt und legten Erwartungen an das Erscheinungsbild (auch bekannt als DX) für API-Entwicklungsteams fest. Der Bedarf an Designkonsistenz war schon zu Beginn der Entwicklung der API-Plattform klar, und die frühen Bemühungen von Paypal (ich war damals tatsächlich Teil dieses Teams!) und Heroku führten zu einigen der ersten Styleguides erfolgreicher Programme öffentlich geteilt.

Während es eine Vielzahl von Automatisierungstools zur Unterstützung bei Styleguides gibt, hat sich das Open-Source-Tool Spectral als Standard für die Definition von API-Linting-Regelsätzen herausgestellt. Durch die vorherige Abstimmung der Konventionen für Pfade, Parameter usw. und die Definition automatisierter Linting-Regeln werden Verzögerungen durch Konflikte darüber vermieden, welche Konventionen „richtig“ sind. Führen Sie die Diskussion einmal und legen Sie Regeln fest. Versuchen Sie, nicht noch einmal darüber zu sprechen. Lassen Sie einfach die Flusenfehler verschwinden!

Die Designstandards, die nicht automatisiert werden können, sollten dokumentiert und den API-Designern leicht zugänglich gemacht werden. Eine Schulung, die die Bedeutung automatisierter und manuell überprüfter Regeln erklärt, kann die Motivation der Entwickler stärken, die Initiative voll zu unterstützen und Überraschungen und Reibungen zu vermeiden.

Während ein API-Aktivierungsteam vorhanden sein sollte, um diese Designstandards zu kuratieren und die Community zu fördern, sollten Autoritäten in jedem Funktionsbereich oder jeder Domäne aktiviert werden.

Obwohl API-Standards wichtig sind, lassen sich Domänenkenntnisse über systemische Einschränkungen, spezifische Kundenbedürfnisse sowie organisatorische Stärken und Schwächen am besten von einem Experten beherrschen, der Teil dieser Welt ist. Wenn von zentralisierten API-Aktivierungsteammitgliedern erwartet wird, dass sie über alles im Unternehmen Bescheid wissen, sind Engpässe, die zu Lieferverzögerungen und zum Rückzug der Entwickler führen, nahezu garantiert.

Schulungsworkshops können eine wirksame Methode sein, um das Bewusstsein für die Bedeutung von API-Standards zu schärfen. Darüber hinaus finden Sie häufig die richtigen KMU, die Governance-Befugnisse bereitstellen. Suchen Sie nach Personen, die eine Leidenschaft für APIs zum Ausdruck bringen (ich bezeichne sie oft als „Bande von Rebellen“), ein Bewusstsein für die Relevanz von Konsistenz und Standards zeigen und den technischen Respekt ihrer Kollegen und/oder Berichte genießen.

An der Entwicklung einer erfolgreichen API sind viele Personen in Ihrem Unternehmen beteiligt, die häufig über unterschiedliche Fähigkeiten verfügen. Einige werden die API erstellen und bereitstellen, während andere auf der strategischen Seite des Geschäftsproblems stehen und den Wert Ihrer API ermitteln. Vergessen Sie auch nicht die geschäftlichen Stakeholder, wenn es darum geht, wen Sie in die Entwurfsprüfung einbeziehen. Oft beziehen wir nur die technische Seite ein, was später zum Scheitern führen kann. Je mehr Perspektiven, desto besser!

Ihre Plattform sollte Produktmanager haben, die sich auf die Gesamtzusammensetzung des API-Portfolios/Katalogs einigen. Kataloge gibt es in vielen verschiedenen Formen und sie organisieren Ihre APIs, damit Sie leichter finden, was Sie brauchen, ohne genau wissen zu müssen, wonach Sie suchen. Es ermöglicht potenziellen Benutzern, die verfügbaren APIs zu durchsuchen, gruppiert nach Funktionalität oder anderen Benutzeranliegen.

Gute Kataloge sind durchsuchbar oder filterbar, sodass Entwickler die Optionen leicht eingrenzen können, und sie bieten vergleichbare, verständliche Details für jede API im Katalog, die einen klaren Weg nach vorne bieten.

Für jede vorgeschlagene neue API sollte so früh wie möglich eine Funktionsübersicht mit Anwendungsfällen und grundlegender Benennung überprüft werden. Dies gewährleistet die Sprachausrichtung, Wiederverwendbarkeit und die allgemeine „Passung“ einer neuen API gegenüber der größeren Plattformperspektive.

Ihr Aktivierungsteam sollte über Produktmanager verfügen, die für den Portfolio-Ausrichtungsprozess verantwortlich sind, und jeder sollte über eine überschaubare Sammlung von Domänen verfügen. Zumindest ist ein regelmäßiger Treffpunkt für domänenspezifische PMs für Abstimmungsgespräche von entscheidender Bedeutung.

Auch wenn das viel erscheinen mag, denken Sie daran, dass sich API-Standards durch Iteration weiterentwickeln sollten. Während jede API entworfen wird, werden Sie Möglichkeiten erkennen, Standards zu verfeinern. Stellen Sie vor diesem Hintergrund sicher, dass die Grundlagen in Ihren Hausaufgaben behandelt werden, und stellen Sie sicher, dass API-Governors ein klares Verständnis davon haben, wie sie Änderungen an Standards vorschlagen und übernehmen können.

Wenn Sie die oben genannten Voraussetzungen erfüllt haben, gibt es bei der Überprüfung des API-Designs nicht viel zu tun! Wenn domänenzentrierte KMU beteiligt sind, kann die Designprüfung oft weitgehend in die laufenden Designbemühungen integriert werden. Wenn die „Passung“ in die Plattform frühzeitig abgestimmt wird, sollten Designprüfer die Gewissheit haben, dass diese API in das Gesamtbild gehört. Wenn API-Designer außerdem beim Iterieren Linting-Fehler feststellen, sollte es keine Diskussionen über grundlegende Konventionen geben, die über die Aufklärung der Entwickler über die Relevanz verschiedener Linting-Regeln hinausgehen oder einfach nur über die Lösung von Lint-Fehlern.

Nicht alles kann automatisiert werden und manchmal können Produkt- und Architekturanforderungen im Widerspruch stehen. Machen Sie Ihre API-Designüberprüfung zu einem Zeitpunkt, an dem manuell erzwungene Konventionen überprüft, die Kundensprache validiert wird (da dies schwer zu automatisieren ist) und die endgültige Ausrichtung gefestigt wird. Angesichts dieses Umfangs können Besprechungen oft umgangen werden und asynchrone Diskussionen können oft ausreichen.

Am wichtigsten ist, dass Sie die Zykluszeit für die Überprüfung des API-Designs genau im Auge behalten. Sie sollte im Laufe der Zeit deutlich sinken, da sich dezentralisiertere KMU mit bestehenden Standards vertrauter machen und wissen, wie sie neue Standards übernehmen können.

Das Schreiben für InfoQ hat viele Türen geöffnet und die Karrierechancen erhöht Für mich. Ich konnte mich intensiv mit Experten und Vordenkern austauschen, um mehr über die von mir behandelten Themen zu erfahren. Und ich kann meine Erkenntnisse auch an die breitere Tech-Community weitergeben und verstehen, wie die Technologien in der realen Welt eingesetzt werden.

Ich habe das Mitwirkendenprogramm von InfoQ Anfang dieses Jahres entdeckt und es seitdem genossen! Das Peer-to-Peer-Review-System von InfoQ bietet mir nicht nur eine Plattform, auf der ich meine Erkenntnisse mit einer globalen Community von Softwareentwicklern teilen kann, sondern hat auch mein Schreiben erheblich verbessert . Wenn Sie nach einem Ort suchen, an dem Sie Ihr Software-Know-how teilen können, beginnen Sie mit der Mitarbeit bei InfoQ.

Ich habe angefangen, Nachrichten für die InfoQ .NET-Warteschlange zu schreiben, um auf dem neuesten Stand der Technik zu bleiben, aber ich habe so viel mehr daraus gemacht. Ich habe sachkundige Leute kennengelernt, weltweite Sichtbarkeit erlangt und meine Schreibfähigkeiten verbessert.

Redakteur für InfoQ zu werden war eine der besten Entscheidungen meiner Karriere . Es hat mich herausgefordert und mir in vielerlei Hinsicht geholfen, zu wachsen . Wir würden uns über mehr Leute freuentrete unserem Team bei.

InfoQ sucht einen Chefredakteur in Vollzeit dem internationalen, stets remote arbeitenden Team von C4Media beizutreten. Entdecken Sie mit uns die innovativsten Technologien unserer Zeit, arbeiten Sie mit den besten Software-Experten der Welt zusammen und helfen Sie mehr als 1,6 Millionen Entwicklerteams bei der Einführung neuer Technologien und Praktiken, die die Grenzen dessen erweitern, was Software und Teams leisten können!

Jeden Dienstag wird eine Zusammenfassung der Inhalte der letzten Woche auf InfoQ verschickt. Treten Sie einer Community von über 250.000 erfahrenen Entwicklern bei. Sehen Sie sich ein Beispiel an

Wir schützen Ihre Privatsphäre.

Sie müssen ein InfoQ-Konto registrieren oder sich anmelden oder anmelden, um Kommentare zu posten. Aber hinter der Registrierung steckt noch viel mehr.

Holen Sie das Beste aus dem InfoQ-Erlebnis heraus.

Zulässiges HTML: a,b,br,blockquote,i,li,pre,u,ul,p

Zulässiges HTML: a,b,br,blockquote,i,li,pre,u,ul,p

Zulässiges HTML: a,b,br,blockquote,i,li,pre,u,ul,p