Slack über Freude statt Frust bei Development-Teams 6 Tipps für ein nutzerfreundliches API-Design

Anbieter zum Thema

Vogel IT-Akademie

Slack

Schlechtes API-Design verbraucht unnötig Ressourcen und kann so zu einer echten Belastung für Unternehmen werden. Mit sechs API-Designprinzipien lässt sich unnötiger Frust vermeiden. Slack hat einige Tipps für nutzerfreundliches API-Design.

1. Weniger ist mehr

Möglichst bereichsübergreifende und gebündelte Problemlösungen mögen in vielen Fällen hilfreich und zielführend sein. Wenn es um das Design von APIs (Application Programming Interfaces) geht, ist genau das Gegenteil der Fall. Damit Entwicklerinnen und Entwickler APIs gerne nutzen, sollten sie verständlich, einfach skalierbar, leistungsfähig und sicher sein.

E-Book zum Thema

Im eBook „API-Entwicklung“ erfahren Sie, wie moderne API-Architekturen aufgebaut sind, wie sich APIs erstellen und einbinden lassen und welche Werkzeuge es gibt. Darüber hinaus beleuchtet es einige Best Practices.

eBook herunterladen

Daher ist es empfehlenswert, sich beim Design einer API auf einen konkreten Anwendungsfall zu konzentrieren – und diesen schon zu Entwicklungsbeginn klar zu definieren. Bereits bestehende, komplexe APIs lassen sich auch nachträglich noch in einfachere, stärker fokussierte APIs umwandeln.

2. Der erste Eindruck zählt

Für den ersten Kontakt mit einer neuen API ist es wichtig, dass sie verständlich ist und einen schnellen und einfachen Einstieg ermöglicht. Mit einer „Hello World“-Übung können sich Developer innerhalb eines angemessenen Zeitfensters mit ihr vertraut machen. 15 Minuten bis zum ersten API-Aufruf sind erfahrungsgemäß ein guter zeitlicher Richtwert. Mittels einer Metrik „Time to first Hello World“ kann eine Zielvorgabe gegeben werden, wieviel Zeit ein erster Aufruf der API in Anspruch nehmen soll.

Welche Zeitspanne tatsächlich angemessen ist, hängt letztendlich sowohl von der Plattform, als auch von der Erfahrung der Entwicklerinnen und Entwickler ab. Diese Erfahrung sollte nicht nur anhand von „Hello World“, sondern auch an ergänzenden Parametern gemessen werden. Etwa, wie viele User Zugriff auf die App haben.

3. Konsistenz in allen Stufen

Jede gute API braucht intuitive Konsistenz. Einen roten Faden, der den Konsumierenden hilft, eine API zu verstehen, ohne die Dokumentation zu lesen. Das heißt: Die Eigenschaften, die Developer von einer API bereits kennen, sollten sie auch bei allem noch Unbekannten erwarten können. Es ist wichtig, dass sich dies durch alle Teile der API zieht – wie Name, Endpunkte, Eingabeparameter und Ausgabeantworten. Dabei sollten drei Stufen berücksichtigt werden:

• Konsistenz mit Industriestandards: Best Practices, die in der jeweiligen Branche akzeptiert sind, sollten zur Orientierung genutzt werden.

• Konsistenz mit Produkt: Feldnamen sollten an das Produkt angepasst sein. Lieber ausführliche Namen, anstelle von Abkürzungen.

• Konsistenz mit bekannten API-Methoden: Namen bekannter Methoden sollten durchgehend beibehalten werden.

4. Aussagestarke Errors

Langwierige Fehlersuche? Bevor Entwicklungsteams sich das antun, werden sie vermutlich frustriert aufgeben. Fehlern sollte rechtzeitig die nötige Beachtung geschenkt werden, da so zeitintensive und nachträgliche Fehlersuchen abgekürzt werden können.

APIs sollten aussagekräftige, präzise und verständliche Fehler zurückgeben. Mit dem Fehler „name_too_long“ etwa können Entwickelnde wesentlich besser arbeiten, als mit dem Fehler „invalid_name“. Ein kleiner, aber nicht zu unterschätzender Unterschied, der hilft, ein Problem zügig zu lösen.

In der Dokumentation oder an anderer Stelle in der API-Antwort können zusätzlich ausführliche Fehlerformulare ergänzt werden, die Fehlerbeschreibungen, Anleitungen zur Problembehebung oder Links mit weiteren Informationen enthalten.

5. Schlechtes Design, schlechte Leistung

Nicht alle Entwicklerinnen und Entwickler nutzen eine API zwangsläufig auf die gleiche Art und Weise. Bei der einen Anwendung werden kleine Datensätze generiert, bei anderen API-Aufrufen wiederum kann es sein, dass Tausende von Elementen zurückgegeben werden.

Unter schlechtem Design kann schlussendlich auch die Leistung leiden. Daher sollten bei der Entwicklung einer API die folgenden Punkte beachtet werden, damit die API ganz individuell genutzt werden kann:

• Große Ergebnismengen sollten durchnummeriert werden. So wird vermieden, dass das Backend der Webanwendung überlastet wird und Clients verlangsamen, die mit großen Datenmengen nicht umgehen können.

• Die Anhäufung großer Sammlungen sollte vermieden werden. Ein Durchnummerieren ist in diesem Fall zu kompliziert.

• Die Rate der API sollte begrenzt werden, um die Anwendung vor einem Absturz zu bewahren. Mit einer Ratenbeschränkung wird die Infrastruktur begrenzt und gleichzeitig die Zuverlässigkeit und Verfügbarkeit der Anwendung erhöht.

6. Fehlerhafte Änderungen

Bei Produktaktualisierungen bleiben Änderungen der API nicht aus. Was gestern funktioniert hat, soll aber auch morgen noch verlässlich funktionieren. Was also nicht passieren darf, sind fehlerhafte Änderungen, die den Code der Kundinnen und Kunden beschädigen und dazu führen, dass Anwendungen nicht mehr einsetzbar sind.

Sollten einschneidende Änderungen an einer API vorgenommen werden, darf dies – im Interesse der Developer – nicht leichtfertig oder in zu kurzen Zeitabständen erfolgen. Neuerungen sollten rechtzeitig angekündigt und so ein möglichst reibungsloser Ablauf sichergestellt werden.

Die Entwicklung eines eigenen API-Styleguides kann nicht vollständig davor bewahren, falsche Entscheidungen zu treffen. Aber er hilft, Entscheidungen offen, ehrlich und klar zu definieren und zu kommunizieren. Und wenn sich doch eine fehlerhafte Änderung eingeschlichen hat, die sich nicht rückgängig machen lässt? Dann kann ein guter Kommunikationsplan helfen – inklusive Entschuldigung.

Die Bedeutung von APIs sollte auf keinen Fall unterschätzt werden. Diese sechs Tipps bieten eine ideale Grundlage für die Gestaltung eines benutzerfreundlichen API-Designs, um die Erwartungen der Entwicklerinnen und Entwickler zu treffen und unnötigen Frust zu vermeiden.

* Bear Douglas ist Director Developer Relations bei Slack.

E-Book zum Thema

API-Entwicklung

APIs sind das Herzstück moderner Anwendungsarchitekturen und innovativer Geschäftsmodelle der „API-Wirtschaft“. Startups in diesem Bereich fließen üppige Kapitalsummen zu. Entsprechend scheint sich auch das Innovationstempo weiter zu beschleunigen.

Im eBook erfahren Sie mehr über:

• Trends rund ums API-Design
• Moderne API-Architekturen
• Das ABC des API-Designs
• Tools für das API-Management
• Best Practices der API-Entwicklung

eBook „API-Entwicklung“ herunterladen

(ID:47930630)