Gute RESTful APIs.

Gute RESTful APIs

Was ist eine gute API?

Hinweis: Obwohl API nur “Application Programming Interface” bedeutet, geht es in diesem Artikel hauptsächlich um eine Http “RESTful” API, die über das Internet erreichbar ist und Json zurücksendet.

Table Of Contents

Die API ist Ihre Benutzeroberfläche

Eine gut gestaltete API fungiert als benutzerfreundliche Schnittstelle für Entwickler, ähnlich wie eine grafische Oberfläche für Endbenutzer. Genau wie der Erfolg einer Anwendung von ihrer UI/UX abhängt, kann die Qualität einer API ihre Akzeptanz und Nutzbarkeit erheblich beeinflussen. Eine klare, intuitive API kann die Integration unkompliziert machen, während eine schlecht gestaltete zu Frustration und vermehrten Support-Anfragen führen kann.

Interne Codebasen strukturieren

Gut gestaltete APIs verbessern nicht nur die externe Benutzererfahrung, sondern helfen auch, interne Codebasen effektiv zu strukturieren. Sie erzwingen klare Grenzen zwischen Services, fördern Wiederverwendbarkeit und erleichtern eine reibungslosere Wartung und Skalierung.

Gute APIs verbessern die Art, wie Daten gespeichert werden, und werfen Fragen auf wie: “Brauchen wir nicht eine Zeitzone für dieses Datum hier?”, oder “gehört diese Ressource wirklich zu diesem Paket?”.

Wachstum ermöglichen und Support-Aufwand reduzieren

Wenn APIs leicht verständlich und gut dokumentiert sind, können Entwickler sie mit minimaler Unterstützung integrieren. Das reduziert die Anzahl der Support-Anfragen und ermöglicht es Ihrem Team, sich auf kritischere Aufgaben zu konzentrieren. Das ist besonders wichtig, wenn Ihre Organisation wächst und Sie Wachstum von der Einstellung neuer Support-Spezialisten entkoppeln müssen. Gute APIs ermöglichen es Nutzern und Implementierern, Ihre API einfach im echten Self-Service umzusetzen.

Der erste Schritt: API-Richtlinien etablieren

Wenn Ihre Teams keine etablierten API-Richtlinien haben, sollte dies Ihre oberste Priorität sein.

Erfinden Sie das Rad nicht neu!

Meiner Erfahrung nach kann die Übernahme eines Regelwerks mit spezifischen Ausnahmen sehr effektiv sein. Sie könnten zum Beispiel Zalandos API-Richtlinien befolgen, aber eine Ausnahme für die Eigenschaftsbenennung durch Verwendung von camelCase machen. Dieser Ansatz hält die interne Dokumentation und Diskussionen prägnant und fokussiert. Das Gestalten von API-Richtlinien kann zwar zeitaufwändig sein, aber denken Sie daran, dass Ihr primäres Ziel ist, Software effizient zu entwickeln und auszuliefern.

Der “API First”-Ansatz

Bei Unternehmen wie Zalando stellt der “API First”-Ansatz sicher, dass APIs durchdacht entworfen werden, bevor die Implementierung beginnt. So funktioniert es:

  1. OpenAPI-Definition entwerfen: Beginnen Sie mit dem Entwurf der OpenAPI-Spezifikation für den neuen Endpoint. Dies umfasst die Beschreibung des Zwecks des Endpoints, der erwarteten Request- und Response-Formate und aller notwendigen Parameter. Stellen Sie sicher, den Endpoint zu beschreiben und Beispiele hinzuzufügen. Implementieren Sie zu diesem Zeitpunkt keinen Code.

  2. Feedback einholen: Reichen Sie einen Pull Request (PR) mit dem Entwurf bei einem API Chapter oder einer ähnlichen Gruppe in Ihrer Organisation ein. Das kann eine einfache Teams- oder Slack-Gruppe sein. Diese Praxis fördert die Zusammenarbeit und hilft sicherzustellen, dass die API intuitiv ist und den Organisationsstandards entspricht.

  3. Basierend auf Feedback iterieren: Nutzen Sie das Feedback zum PR, um die API-Definition zu verfeinern. Dieser Prozess kann die Verbesserung von Beschreibungen, Vereinfachung von Endpoint-Strukturen oder Klärung von Payloads umfassen.

  4. Mit der Implementierung beginnen: Sobald das API-Design genehmigt ist, fahren Sie mit der Implementierung fort. Dies stellt sicher, dass der Entwicklungsprozess mit den vereinbarten Spezifikationen übereinstimmt.

Die Bedeutung guter API-Dokumentation

Seniorität und Dokumentation

In meiner Career Ladder mache ich es explizit: “Gute Dokumentation und leicht verständliche API-Beschreibungen zu schreiben ist ein klares Zeichen eines Senior Developers.”

Wenn Sie einen Endpoint namens “appointment” mit der Beschreibung “creates appointment” haben (keine Beispiele, keine weiteren Details zur Geschäftslogik), dann ist das nicht gut genug. Es ist ein Zeichen dafür, dass der Autor noch kein Senior Engineer ist.

“Gut schreiben” ist entscheidend, weil klare Dokumentation den Nutzern hilft, komplexe Konzepte zu erfassen und APIs effektiv zu nutzen. Wenn Sie dies als herausfordernd empfinden, suchen Sie Mentoring und Unterstützung, um Ihre Fähigkeiten zu verbessern. Es gibt sogar ein hervorragendes Buch zu diesem Thema!

Best Practices für gute API-Dokumentation

  • Akronyme vermeiden: Verwenden Sie vollständige Begriffe, um Missverständnisse zu vermeiden.
  • Versetzen Sie sich in die Lage des Nutzers: Erklären Sie Konzepte klar und antizipieren Sie mögliche Verwirrung. Beschreiben Sie die Geschäftslogik gut und in einfachen Worten. Beginnen Sie mit den Grundlagen. Wie würde z.B. ein Nutzer ein Auth-Token bekommen?
  • Verwenden Sie Visualisierungen: Diagramme können komplexe Interaktionen vereinfachen und Datenflüsse veranschaulichen.
  • Bieten Sie Anwendungsfälle und Beispiele: Erklären Sie, wann und warum ein Endpoint verwendet werden sollte, mit praktischen Beispielen.
  • Fügen Sie Code-Beispiele hinzu: Bieten Sie Beispiele, wie z.B. curl-Befehle, um Requests und Responses zu demonstrieren.

Eine einzige Quelle der Wahrheit pflegen

Die Verwaltung von API-Dokumentation kann herausfordernd sein, besonders wenn Systeme wachsen. Es ist verlockend, separate Dokumente für technische Spezifikationen und Benutzeranleitungen zu pflegen, aber dies kann zu Diskrepanzen und erhöhtem Wartungsaufwand führen.

Einheitliche Dokumentation

  • Eine Quelle: Verwenden Sie eine einzige Plattform, wie OpenAPI, um Ihre API zu dokumentieren. Das gewährleistet Konsistenz und reduziert die Wahrscheinlichkeit, dass die Dokumentation auseinanderdriftet.
  • Verbesserte Visualisierung: Tools wie Redoc können OpenAPI-Dateien in benutzerfreundliche Dokumentation umwandeln, die es Entwicklern erleichtert, Ihre API zu navigieren und zu verstehen.

Fazit

Schöne Json RESTful APIs zu erstellen erfordert durchdachtes Design, klare Dokumentation und Zusammenarbeit. Durch die Übernahme eines “API First”-Ansatzes, den Fokus auf exzellente Beschreibungen und die Pflege einer einzigen Quelle der Wahrheit können Sie APIs bauen, die nicht nur funktional sind, sondern auch Freude bei der Nutzung bereiten. Denken Sie daran: Ihre API ist die Schnittstelle Ihres Produkts zur Welt - machen Sie sie wertvoll :)

Mehr

Related posts

Imprint | Privacy Policy