🍫 👩‍✈️ 😙 API Style Guide, oder lassen Sie Benutzer nicht nachdenken 💪🏻 👨🏾‍💼 👉

Hallo! Mein Name ist Lesha Rutskoi und ich bin Produktmanager bei Wrike. Zuvor arbeitete er bei Adform und PandaDoc. In den letzten fünf Jahren habe ich alles getan, was mit Integrationen und APIs zu tun hat.

Wrike ist ein SaaS-Produkt für die Zusammenarbeit und das Projektmanagement. Wir möchten, dass Entwickler ihre Lösungen auf Wrike-Basis erstellen. Dazu muss unsere API bequem sein. Gleichzeitig haben wir 9 Büros auf der ganzen Welt, von denen 3 Entwicklungsbüros sind. Es ist ziemlich schwierig, eine konsistente API mit verteilten Teams zu erstellen, die verschiedene Sprachen sprechen. Es besteht eine wachsende Wahrscheinlichkeit, dass sich ihre Entscheidungen widersprechen. In diesem Fall kann man nicht auf ein einheitliches Regelwerk für alle verzichten.

Wenn Sie auch verteilt arbeiten und Ihre eigene API erstellen, kann Ihnen die Style Guide-API helfen. Ich möchte Ihnen sagen, welche häufigen Probleme es löst und wie es Entwicklern das Leben erleichtert. Ich werde auch meine Erfahrungen beim Schreiben und Implementieren meines eigenen API Style Guide im Unternehmen teilen.

Warum brauchen wir eine bequeme API?

Viele Leser mussten wahrscheinlich Probleme mit der nicht so praktischen API lösen. Ja, das ist nicht sehr einfach und dauert länger, aber normalerweise können Sie das Problem trotzdem lösen.

Warum sollten Sie dann Zeit und Teamarbeit verschwenden, um die API zu verbessern? Die Antwort ist ganz einfach: Sehr oft wird die Entscheidung über die Verwendung Ihres Produkts von Entwicklern getroffen, insbesondere wenn es um APIs und Integrationen geht. Daher ist es wichtig, nicht nur an die Benutzererfahrung (User Experience, UX) zu denken, sondern auch an die DX - Entwicklererfahrung.

Ich werde ein Beispiel geben. Ich habe einmal in einem Team gearbeitet, das für die gesamte Produktintegration verantwortlich war. Oft kam Mitte des Quartals, als unsere Pläne bereits skizziert waren, ein Vermarkter und sagte: „Z hat einen neuen Marktplatz geschaffen und wird die nächste Version seiner Plattform veröffentlichen. Bald haben sie eine coole öffentliche Veranstaltung, bei der wir über unsere Integration und unseren Erfolg sprechen können! Es wird großartig sein, wenn wir diese Integration jetzt schnell schreiben. “ Was haben wir in diesem Fall gemacht? Wenn ein erfahrener Entwickler in einem Team den minimal funktionierenden Prototyp in drei Tagen herstellen konnte, gelang es uns meistens in zwei oder drei Wochen, die Aufgabe in einen perfekten Zustand zu bringen. Wenn ein paar Tage fehlten, waren die API und die Dokumentation mittelmäßig.Es war sinnlos für uns, Pläne neu zu zeichnen und neue Integrationen vorzunehmen - trotzdem hätte bis zum Fälligkeitsdatum nichts Wertvolles geklappt. Denken Sie daran, dass sich Ihr Produkt möglicherweise in einer solchen Situation befindet. Die Partner entscheiden, ob sie sich mit Ihnen befassen, je nachdem, wie schnell und bequem Sie mit Ihrer API arbeiten können.

Aber kaum jemand möchte eine schlechte API entwerfen. Warum wird jeder anders? In der Regel entwickelt sich eine API wie folgt. Wenn ein Startup wächst und die ersten Kunden dazu kommen, legt eines der Teams seinen Endpunkt fest und beschließt, die Version an die URL zu übertragen:

Bild

Allmählich erscheinen neue Kunden und neue Anforderungen. Die Jungs aus dem zweiten Team sind in die Arbeit involviert, die glauben, dass es besser ist, ihre eigenen Medientypen für die Versionierung zu verwenden:

Bild

Nach einer Weile kommt das dritte Team. Auf einer Konferenz erfahren sie, dass Stripe seine API mit wichtigen Veröffentlichungsdaten versioniert. Und sie entscheiden sich dafür, dasselbe zu tun:

Bild

Das Ergebnis ist eine API, in der es drei Versionsmethoden gibt. Alle Methoden funktionieren, aber anders.

Als Entwickler wäre es für mich unpraktisch, eine solche API zu verwenden. Und der Grund ist nicht, dass ich einen Versionsansatz allen anderen vorziehe. Es ist unpraktisch, nur mehrere Methoden gleichzeitig zu verwenden. Sie müssen dreimal Code schreiben, der mit der API funktioniert, oder drei verschiedene Bibliotheken verwenden. Und das bedeutet, dass es dreimal so viele Fehler gibt.

Und es gibt Daten und Zeiten. Selbst mit dem Standardansatz können Daten auf verschiedene Arten übertragen werden: nach der Zeitzone Ihres Servers, nach GMT, nach der Zeit auf dem Client in Unix-Zeit. Clients müssen alle Daten in ein Format bringen.

Fehlermeldungen machen im Allgemeinen alles anders. Zum Beispiel so:

Bild

Oder so:

Es gibt auch meine Lieblingsfehlermeldung - eine leere Antwort:

Bild

Nun, nur ein Klassiker - die Antwort lautet 200 OK. Darin liegt JSON mit einer Beschreibung dessen, was schief gelaufen ist.

Meiner Meinung nach ist die Konsistenz das Wichtigste an einer guten API . Es spielt keine Rolle, welchen Versionsansatz Sie wählen, die Hauptsache ist, dass er in der gesamten API gleich ist. Eine noch erfolgreichere Lösung wäre der beliebte Ansatz, den andere Unternehmen bereits verfolgen. Höchstwahrscheinlich sind Ihre Kunden bereits darauf gestoßen und verfügen über vorgefertigten Code oder eine Bibliothek. Sie müssen nicht noch einmal darüber nachdenken, Sie können vorgefertigte Werkzeuge verwenden.

Ein einziger Ansatz zum Erstellen einer API ist besonders wichtig für große Unternehmen mit verteilten Teams. Wenn zehn Personen im Raum ein Startup erstellen, kann jeder Entwickler einfach einen Nachbarn auf die Schulter klopfen und die Hauptprobleme während der Codeüberprüfung vereinbaren oder sehen. In einem großen Unternehmen wird es schwieriger.

Die Style Guide API hilft Ihnen bei der Lösung solcher Probleme. Dies ist ein Dokument, das die Entwurfsprinzipien Ihrer API beschreibt. Wenn alle dieselben Ansätze verwenden, wurde die API anscheinend von einer Person und nicht von vielen verschiedenen Teams entwickelt. Dieser Ansatz ähnelt dem Code Style Guide, wenn sich die Teams darauf einigen, wie sie Code schreiben. Eine Person aus einem Team kann sich die Codebasis eines anderen Teams ansehen und schnell verstehen, was dort passiert.

Wie erstelle ich meinen eigenen API Style Guide?

Arnauld Lauret (bekannt als API Handyman ) hat eine coole Seite erstellt - API Stylebook . Er stellte einen öffentlich zugänglichen Style Guide zusammen, den verschiedene Unternehmen (Cisco, Google, Red Hat, Regierungsbehörden und viele andere) öffentlich zugänglich machten.

Die Richtlinien sind auf der Website in Themen unterteilt. Wenn Sie beispielsweise an einer Versionierung interessiert sind, können Sie auf der Registerkarte Versionierung herausfinden, wie verschiedene Unternehmen dieses Problem lösen.

Lerne aus den Erfahrungen anderer! Es ist jedoch keine gute Idee, den Style Guide eines anderen vollständig zu kopieren. Trotzdem löst er die Probleme eines anderen Unternehmens, nicht Ihres.

In Ihrem Style Guide sollten Sie Themen hinzufügen, die Ihrem Unternehmen nahe stehen, und Ihre Probleme lösen. Vielleicht haben Sie viele mobile Anwendungen, und die Größe der Antwort ist Ihnen wichtig. Beschreiben Sie dann die mit diesem Aspekt verbundenen Prinzipien. Oder Sie haben mit internen Teams vereinbart, dass es Zeit ist, den Monolithen in Microservices zu verwandeln, die über Message Broker miteinander kommunizieren. In diesem Fall müssen Sie die Prinzipien, nach denen Sie Kafka oder ein anderes Tool verwenden möchten, in den API Style Guide aufnehmen.

Was soll noch in die Style Guide-API aufgenommen werden?

Außerdem sollte der Style Guide die Grundwerte und technischen Ansätze enthalten, an die sich das Unternehmen hält.

Was können sie sein?

Write APIs in English. , . - , , . Style Guide, , .
API First principle. API : , , frontend-. , API . , , .
Verwenden Sie REST und JSON. Dies kann wichtig sein, wenn Sie möchten, dass möglichst viele Benutzer Ihre API oder Plattform verwenden. Trotz der Tatsache, dass GraphQL seit 2017 immer beliebter wird, weiß nicht jeder davon. Die meisten Entwickler haben es höchstwahrscheinlich noch nie verwendet, was bedeutet, dass sie die Zeit für das Eintauchen und Entwickeln verlängern. Warum Komplexität schaffen?

Darüber hinaus können die Grundprinzipien zu Themen festgelegt werden. Im Rahmen der Verwendung von REST und JSON können Sie beispielsweise leicht festlegen, welche Themen im Handbuch beschrieben werden sollen:

Bevorzugen Sie die REST-API mit JSON-Nutzdaten
- HTTP-Anfragen
- HTTP-Statuscodes
- Json

Weiter zu jedem Thema können Sie die Regeln festlegen, die alle Teams im Unternehmen befolgen sollten:

HTTP-Anfragen
- MUSS HTTP-Methoden korrekt verwenden
- Benutzerdefinierte HTTP-Header sollten der Namenskonvention folgen

Ich mag den Ansatz, der die Notwendigkeit beschreibt, die Regeln durch die Verben MUST, SHOULD oder MAY (aus RFC 2119 entlehnt ) zu befolgen . Dann unterscheidet jeder, der den Style Guide liest, zwischen verbindlichen Regeln und Empfehlungen.

So sieht es beispielsweise in Zalando aus :

Bild

Dinge, die Sie beim Starten des Style Guides beachten sollten

. , . , , . , , . API management , . API.
. - 15- . rate limiting, .. — , , - .
. , OAuth, REST. , , , scopes .
. , , .
. , . , . . . , .
. , , .
. , , .. : , «user», , «user», .
. , — . , (OpenAPI-, -) . .

API Style Guide?

Sie haben Ihren API Style Guide erstellt und müssen ihn nun noch implementieren. Das ist auch nicht einfach. Ich werde meine Erfahrungen mit der Implementierung des API Style Guide an einem der Orte teilen, an denen ich gearbeitet habe. Das Unternehmen hatte eine komplexe Struktur: Hunderte von Ingenieuren, Dutzende verteilter Teams in vier Entwicklungsbüros, Kollegen sprachen verschiedene Sprachen.

Zuerst müssen Sie die Stakeholder überzeugen. Und hier sprechen wir oft sowohl über technische Leiter in verschiedenen Bereichen als auch über Unternehmensvertreter. Jeder sollte verstehen, welche Probleme wir lösen möchten und wie der Style Guide helfen kann. In meinem Beispiel haben alle Beteiligten verstanden, dass eine gute API ein wichtiger Vorteil ist. Viele Kunden kamen mit einer solchen Anfrage, und die Wettbewerber dösten nicht ein und erweiterten aktiv den Umfang der über ihre API verfügbaren Möglichkeiten.

Der nächste Schritt besteht darin, ein Team zu finden, das dies erledigt. In meinem Fall hatte das Unternehmen bereits ein separates Team, das eine externe API unterstützte. Sie verstand die Notwendigkeit von Veränderungen am besten, weil sie ständig mit Schwierigkeiten in ihrer Arbeit konfrontiert war. Die Mitglieder dieses Teams freuten sich über die Teilnahme an dem Projekt.

Wie hat das Team die Style Guide API implementiert?

Sie sprach auf internen Konferenzen und Hackathons über die Initiative, damit jeder im Unternehmen verstehen würde, was besprochen wurde. Dies trug dazu bei, Gleichgesinnte anzuziehen, die in den nächsten Phasen sehr nützlich waren.
Vorbereitung eines Entwurfs eines Style Guides, der anschließend mit den API-Champions vereinbart wurde (über sie etwas weiter).
Präsentierte das Projekt den Teams. Die Jungs gingen zu jedem Entwicklungsbüro und sprachen mit fast allen Teams, erklärten die Bedeutung des Projekts und führten Schulungen durch.
Hilft beim Design der API. Für viele Teams war es schwierig, beim ersten Mal alles auf dem Guide zu machen. Hilfe und zusätzliche Erklärungen haben sich hier als nützlich erwiesen, insbesondere in ungewöhnlichen Situationen.
Eine Überprüfung durchgeführt. Es war wichtig zu überprüfen, ob alle Teams gemäß dem Style Guide handeln.

Für ein Team in einem großen Unternehmen ist es sehr schwierig, solche bedeutenden Änderungen umzusetzen. Brauche Unterstützung. Hier wurden API-Champions verbunden - Architekten und Techniker jeder Richtung, die dazu beitrugen, die Idee in ihre Teams und Abteilungen zu integrieren.

Wenn wichtige Änderungen vorgenommen werden, tritt häufig Unzufriedenheit auf. In diesem Fall benötigen Sie Autorität, die diese Menschen von der Notwendigkeit einer Veränderung überzeugen kann. Tehliden sind dafür am besten geeignet.

API-Champions diskutierten in einem separaten Slack-Kanal aufkommende Probleme und Vorschläge. Kleinere Änderungen wurden sofort eingeführt, während größere eine ausführliche Diskussion erforderten. In diesem Fall schrieb der Initiator einen offiziellen Vorschlag: Welches Problem muss gelöst werden, welche Lösungsmethoden gibt es bereits, welche Vor- und Nachteile haben sie. Dann versammelten wir uns 1-2 Tage vor Ort außerhalb des Büros, diskutierten Ideen, wählten eine Lösung und reparierten sie. Dann erzählten wir unseren Teams von der Entscheidung, die wir getroffen haben: Warum wir sie getroffen haben und was als nächstes getan werden muss.

Außerdem halfen API-Champions bei der Durchführung von Überprüfungen in ihren Bereichen. Die Jungs in ihren Teams wandten sich zuerst an sie, und dann wurde die endgültige Überprüfung von dem Team durchgeführt, das den Style Guide erstellt hat.

Nach einiger Zeit begann sich im Unternehmen eine API-Community zu bilden. Darunter waren Personen, die mehrere Überprüfungszyklen durchlaufen haben und herausgefunden haben, was ein gutes und korrektes Design ist, warum es benötigt wird und wie es hergestellt wird. Wir haben einen großen Chat erstellt, in dem jeder eine Frage stellen konnte, und Mitglieder der API-Community halfen bei der Lösung.

Sie können den Ansatz nicht nur auf technischer Ebene implementieren. Vertriebs-, Support- und Marketingteams sollten auch verstehen, welche Benutzerszenarien von der API abgedeckt werden, welchen Wert sie hat, wie sie sich auf die Unternehmensstrategie bezieht und wie Informationen darüber ordnungsgemäß an Kunden übermittelt werden.

Wir haben versucht, all dies in das Onboarding der meisten Teams des Unternehmens einzubeziehen, auch der nicht-technischen. Dies ist auch notwendig, damit jeder versteht, wann, in welchen Fällen und zu wem Sie um Hilfe kommen können.

Automatisierung

Das letzte wichtige Thema ist die Automatisierung von Routineprozessen. Die Überprüfung kann als Paradebeispiel dienen. In einem großen Unternehmen mit einer großen Anzahl von Teams müssen Sie höchstwahrscheinlich viele Überprüfungen durchführen. Ich möchte keine Zeit mit grundlegenden Problemen wie einer fehlenden Fehlerbeschreibung oder einem falschen ID-Format verschwenden.

Einige Tools können dabei helfen:

Zally von Zalando prüft, ob die OpenAPI-Spezifikation mit Ihrem API Style Guide übereinstimmt. Die Grundkonfiguration von Zally überprüft die Konformität mit dem Zalando Style Guide. Sie können jedoch Ihre eigenen Regeln neu definieren und hinzufügen.
Apiarys Dredd prüft, ob die endgültige REST-API-Implementierung Ihrem Design entspricht, nämlich OpenAPI-, Blueprint- oder RAML-Spezifikationen.

Dieser Artikel ist eine Abschrift meines Vortrags mit Miros Platform Developers Conference . Das Video der Rede finden Sie hier .

Gerne beantworte ich Ihre Fragen zur Implementierung des API Style Guide. Es wird auch cool sein, wenn Sie eine ähnliche Erfahrung teilen!

Besonderer Dank geht an Daria Ivanova für ihre Hilfe bei der Vorbereitung dieses Artikels!