Alessandro RodiVon Alessandro Rodi / 06.07.21
the-dos-and-don-ts-of-designing-and-implementing-of-rest-apis
Foto von Neven Krcmarek von Unsplash
arrow-back

Zu den vielfältigen Aufgaben einer Web-Agentur gehört oft auch die Realisierung von APIs. Kurz gesagt, APIs sind Dienste, die eine Anwendung anderen Anwendungen zur Verfügung stellt, um Daten anzuzeigen oder zu ändern. Genauso wie es möglich ist, Daten über Webseiten zu visualisieren und zu ändern, ist es möglich, die gleichen Operationen über APIs durchzuführen. Stellen Sie sich beispielsweise vor, Sie möchten Ihren Kontonamen ändern: Das können Sie über eine Webseite oder auch durch eine API-Anfrage an einen bestimmten Dienst erreichen. Was aber, wenn Sie 1000 Namen bearbeiten wollen? Über eine Webseiten wäre diese Aufgabe sicherlich sehr zeitaufwendig und monoton. Mit Hilfe von APIs kann dieser Prozess automatisiert werden, indem man ein kleines Stück Code schreibt, das automatisch den API-Dienst 1000 Mal aufruft und alle Namen aktualisiert.

In diesem Beitrag werde ich erklären, wie wir bei Renuo REST-APIs entwerfen und implementieren, die zuverlässig, leistungsfähig, einfach zu warten, erweiterbar und überwachbar sind.

Dokumentation

Wenn wir APIs für Ihre Kunden definieren, dokumentieren wir sie immer über Swagger und stellen nicht nur die Swagger-Datei, sondern auch eine Instanz von Swagger UI zur Verfügung, in der die Kunden die Dokumentation leicht lesen und die Dienste testen können.

Die API-Dokumentation muss sowohl für Menschen als auch für Maschinen leicht zu verstehen sein.

Eine gute Dokumentation sollte immer auf dem neuesten Stand sein und viele Beispiele enthalten, damit sie für die Kunden einfach zu benutzen ist. Die Bereitstellung einer Testumgebung ist für unsere Kunden von entscheidender Bedeutung, damit sie unser System schnell adaptieren können.

Schließlich wird durch die Bereitstellung von Beispielen in echten Programmiersprachen die Produktivität zusätzlich gesteigert und unsere API-Dokumentation wirklich vervollständigt.

Bei Renuo verwenden wir den OpenAPI 3-Standard, und wir installieren immer eine Instanz von SwaggerUI, um die Dokumentation lesen und darauf zugreifen zu können. Sowohl für «interne» APIs, d. h. nur von uns verwendete, als auch für «externe» APIs, d. h. öffentlich zugängliche.

Verlässlichkeit

Die Zuverlässigkeit der API kann anhand verschiedener Aspekte bewertet werden. Zunächst einmal die Geschwindigkeit: Wie lange braucht eine API, um eine Antwort zu liefern? Zuverlässige APIs müssen schnell sein. Bei Renuo setzen wir auf Ruby On Rails: Die Zuverlässigkeit von APIs, die mit diesem Framework entwickelt wurden, ist bis heute unbestritten. Viele Unternehmen auf dem Markt nutzen Rails, um ihre APIs zu entwickeln, und bedienen bis zu 2,8 Milliarden Anfragen pro TagWir wissen, dass, wenn Ruby On Rails in der Lage ist, die Anforderungen von GitHub, Shopify und Netflix zu erfüllen, es auch den Anforderungen unserer Kunden gerecht wird.

Neben der Geschwindigkeit ist ein zweiter Parameter definitiv die Betriebszeit Ihrer API. Dies ist kein Parameter, der sich auf die Anwendung bezieht, sondern auf die verwendete Infrastruktur. Bei Renuo setzen wir für internationale Kunden auf Heroku und für Schweizer Kunden auf lokale Anbieter. Die Betriebszeit wird jeden Monat von uptimerobot berechnet, der Probleme anzeigt und meldet.

Ein letzter Parameter für die Bewertung der Zuverlässigkeit ist sicherlich die Quantität und Qualität der Fehler. Wir unterscheiden zwei Arten von Fehlern: verwaltete und nicht verwaltete.

Verwaltete Fehler, d. h. solche, die normalerweise einen HTTP-Code zwischen 300 und 499 zurückgeben, werden beim Parameter «Zuverlässigkeit» nicht berücksichtigt: Diese Fehler sind, wie gesagt, verwaltet und werden daher erwartet. Einer der bekanntesten Fehler ist der 404-Fehler, der angezeigt wird, wenn eine Seite oder eine Datei nicht gefunden werden kann.

Nicht verwaltete Fehler, in der Regel mit dem HTTP-Code 500, sind diejenigen, die zur Zuverlässigkeit eines Systems beitragen. Eine einwandfrei implementierte API wird niemals Fehler mit dem Code 500 zurückgeben. Solche Fehler sind unerwartete Situationen, die nicht richtig behandelt werden.

Wenn eine API einen 500-Fehler zurückgibt, verringert dies ihre Zuverlässigkeit. In diesen Fällen ist es sehr wichtig:

  • Teilen Sie dem Kunden keine Einzelheiten über den Fehler mit. Da der Fehler nicht verwaltet wurde, haben Sie keine Kontrolle darüber, welche Daten, einschliesslich der sensiblen Informationen der Kunden, offengelegt werden könnten.
  • Behalten Sie das gleiche Design bei, d.h. geben Sie keine HTML- oder andere Datenstrukturen zurück;
  • sofort die Einzelheiten des Vorfalls an ein Protokollierungssystem senden;
  • über einen Prozess innerhalb des Entwicklungsteams verfügen, um das Problem so schnell wie möglich zu identifizieren, zu analysieren und zu beheben;
  • Kommunikation mit dem Kunden, dass das Problem behoben wurde.

Um mit dem Kunden kommunizieren zu können, ist eine korrekte Verwaltung des API-Key erforderlich, wie wir später noch sehen werden.


Entwurf

Das API-Design ist sehr wichtig und muss von Anfang an festgelegt werden. Eine Änderung des Designs Ihrer APIs kann sehr teuer werden, und Ihre Kunden könnten gezwungen sein, umfangreiche und teure Änderungen vorzunehmen, wenn sich das Design zwischen Version 1 und Version 2 erheblich ändert. Es ist daher sehr wichtig, von Anfang an das richtige Design zu wählen.

Bei Renuo beginnen wir immer mit dem JSONAPI-Standard. Wir glauben nicht, dass es in den meisten Fällen der beste Standard ist, aber es ist ein Standard.

Wenn Sie sich bei der Definition und dem Design Ihrer API auf einen Standard verlassen, können Sie sich alle Diskussionen sparen. Dies führt zu einer erheblichen Zeitersparnis sowohl bei der anfänglichen Definition als auch bei der anschliessenden Implementierung.

Da Sie sich auf einen Standard verlassen, gibt es bereits viele Bibliotheken für die gängigsten Sprachen, die JSONAPI implementieren und darüber kommunizieren können.


Wartung und Versionierung

Wie pflegt und versioniert man seine APIs richtig? Im Internet finden Sie viele Techniken zur Versionierung von REST-APIs. Bei Renuo verwenden wir einen eigenen Header namens API-Version. Dieser Parameter ist optional und standardmässig auf 1 gesetzt.

Wir verwenden ein semantisches Versionierungssystem in unserer API-Entwicklung. Das bedeutet, dass unsere API ein dreistufiges Zahlenformat hat: 1.0.2.

Da Patches und Minor-Releases immer abwärtskompatibel sind, hat der Kunde keine Wahlmöglichkeit: Er hat nur die Möglichkeit, die Hauptversion zu ändern und sich so an bahnbrechende Änderungen anzupassen.

Für die API-Versionierung ist es auch sehr wichtig, ein Protokoll darüber zu führen, welche Version Ihre Kunden derzeit verwenden. Auf diese Weise können Sie Kunden, die ältere Versionen verwenden, kontaktieren und sie auffordern, auf neuere Versionen des Systems umzusteigen.

Es ist sehr wichtig, dass das API-Entwicklungsteam bei API-Änderungen immer sehr vorsichtig ist. Es liegt in der Verantwortung des Teams, korrekt zwischen Patches, kleineren und grösseren Änderungen zu unterscheiden und diese Änderungen korrekt zu veröffentlichen.


API-Schlüssel

Wir haben bereits über Kunden, die Kommunikation mit Kunden und die Überwachung gesprochen.

Bei Renuo richten wir für jeden Kunden von Anfang an einen API-Key ein.

API-Schlüssel werden verwendet, um den Nutzer unserer API eindeutig zu identifizieren.

Daher führen wir in der Datenbank eine Liste unserer API-Clients mit den folgenden Daten:

  • API-Schlüssel: verschlüsselter Schlüssel, der für den Zugriff auf die Dienste verwendet wird
  • Name: ein eindeutiger Name zur Identifizierung des Kunden
  • Email: die Email-Adresse der Person, die kontaktiert werden soll
  • API-Version: die standardmässig verwendete API-Version, falls nicht im Header angegeben
  • Allowlist: ein regulärer Ausdruck, um festzulegen, welche APIs zugänglich sind
  • Denylist: ein regulärer Ausdruck, um zu definieren, welche APIs nicht zugänglich sind.

Ein Client kann eine API verwenden, wenn:

  • der Schlüssel korrekt ist;
  • die Version korrekt ist;
  • der API-Pfad in der Zulassen-Liste enthalten ist;
  • der API-Pfad nicht in der Denyliste enthalten ist.
Ein Protokollierungssystem zeichnet auch alle von jedem Client getätigten Aufrufe auf. Auf diese Weise wissen wir immer:
  • wie viele Aufrufe für jede Version der API getätigt werden und von wem;
  • wie viele unbehandelte Fehler aufgetreten sind und wer von ihnen betroffen war;
  • die durchschnittlichen Antwortzeiten für jeden Kunden;
  • und vieles mehr...


Überwachung

Der letzte Aspekt, über den wir sprechen sollten, ist die API-Überwachung. Zusammen mit dem oben erwähnten API-Key-System führen wir stets ein Protokoll der API-Anfragen und zeichnen diese auf:

  • Verwendeter API-Key
  • Verwendete API-Version
  • API-Anfrage: Pfad + Methode
  • Text der Anfrage
  • Inhalt der Antwort
  • Zurückgegebener HTTP-Code
  • Dauer der Anfrage

Darüber hinaus senden wir für jeden Fehler, der innerhalb der Anwendung auftritt, ein Signal an Sentry, ein System zur Fehlerüberwachung und -verwaltung.

Auf diese Weise haben wir die vollständige Kontrolle über unsere API und alle Daten, die wir benötigen, um mögliche Probleme zu analysieren.

Aber kein Tool ist ausreichend, wenn es keinen gut definierten und effizienten Prozess für die Überwachung gibt. Das schwache Glied in der Kette, und zwar nicht nur bei der API-Entwicklung, sondern bei der Softwareentwicklung im Allgemeinen, besteht darin, dass es trotz der bestmöglichen Überwachungssysteme nicht immer einen gut definierten Prozess der Verantwortlichkeit innerhalb der Teams gibt.

Es kommt häufig vor, dass Fehler und Überwachungen einfach ignoriert werden, da es keine definierte Kette von Verantwortlichkeiten gibt.

Bei Renuo gibt es nicht nur die beste Software, die man für Geld kaufen kann ;), sondern auch eine tägliche Überwachung und Bearbeitung der Fehler, die am Vortag aufgetreten sind. Nicht ein einziger Fehler wird ignoriert.

Abschliessende Überlegungen

Die Definition und Offenlegung von APIs ist einfach, aber es richtig zu machen, ist nicht selbstverständlich. Unserer Erfahrung nach sind die in diesem Artikel aufgeführten Punkte am wichtigsten.

Wenn Ihr API-Design und Ihre Überwachung gut strukturiert sind, werden Ihre Kunden dankbar sein.

Ausserdem ist die Einhaltung dieser Best Practices bei der Entwicklung interner APIs definitiv hilfreich.

Auf technischer Ebene wurden viele der von uns verwendeten Tools und bewährten Verfahren als Open Source veröffentlicht. Zu den neuesten Bibliotheken, die wir veröffentlicht haben, gehört der Rails API Logger, der bei der Überwachung hilft.

Diese Beiträge könnten Sie ebenfalls interessieren:

🎂