7 Tipps zur Erstellung besserer Rest-APIs

Robert Sfichi am 02. Juni 2021

Die Erstellung sicherer, benutzerfreundlicher RESTful-APIs ist eine der Aufgaben, die Entwicklern viel Kopfzerbrechen bereiten. REST-APIs sind seit langem der Industriestandard für die Erleichterung der Kommunikation zwischen Back-End- und Front-End-Anwendungen.

Unser Team ist sich der Bedeutung einer gut konzipierten API bewusst und hat die besten Praktiken zusammengetragen, um Entwicklern bei der Erstellung einer einwandfreien REST-API zu helfen.

Lassen Sie uns alles über die wichtigsten Details mit Ihnen teilen!

Tipps für die Erstellung einer besseren REST-API

Einige der häufigsten Fehler, die Entwickler bei der Entwicklung einer REST-API machen, sind:

Unzureichend verfasste Dokumentation
Undefinierte Architektur
Inkonsistente Endpunktdefinitionen
Unklare Kommunikation
Unzureichende Sicherheitsmaßnahmen

Wir leben nicht in einer perfekten Welt. Es ist normal, Fehler zu machen. Bevor man sich jedoch auf ein Projekt einlässt, muss man alle Vorsichtsmaßnahmen treffen und alle Risiken oder Fehler kennen, die man machen könnte.

Das gilt auch für unseren Fall. Deshalb gibt Ihnen unser Team in den folgenden Abschnitten einige Tipps, die auf seiner persönlichen und beruflichen Erfahrung beruhen.

1. Dokumentation ernst nehmen

Die Dokumentation Ihrer API hilft Ihnen und Ihrem Team, den Datenfluss der Anwendung besser zu verstehen. Bei der Erstellung einer API werden unweigerlich Probleme auftreten. Dinge wie Bibliotheksaktualisierungen, API-Versionen oder Sicherheitsprobleme werden dazu führen, dass Sie sich wünschen, Sie hätten die Dokumentation geschrieben.

Auf diese Weise verringern Sie auch den Aufwand für das Onboarding neuer externer oder interner Softwareentwickler und erleichtern dem Team die Durchführung von Updates und Wartungsmaßnahmen. Versuchen Sie, ihnen den Vorteil zu geben, auf Ihrer API aufbauen zu können, auch wenn sie die von Ihnen verwendeten Technologien nicht vollständig verstehen.

Zum Glück ist es heutzutage viel einfacher, Dokumentation zu erstellen. Tools wie Apiary, Swagger, Raml und viele andere helfen Entwicklern dabei, Dokumentation im Handumdrehen zu erstellen. Sie können sich jederzeit von nützlichen, gut geschriebenen Dokumentationen wie The Rust Docs, GitHub Developer Docs, Ruby On Rails Guides, CasperJS oder Moment.js inspirieren lassen.

2. Fokus auf Sicherheit

Wir sollten immer versuchen, die Kommunikation zwischen dem Client und dem Server privat zu halten.

Entwickler verwenden APIs, um ihre Dienste aufzubauen und Daten zu übertragen. Wenn eine API kaputt ist, offengelegt wird oder schwerwiegende Datenschutzverletzungen aufweist, wird sie mit Sicherheit von keinem Entwickler ausgewählt werden.

Versuchen Sie, die Anfrageparameter von Anfang an zu validieren. Implementieren Sie Validierungsprüfungen und blockieren Sie jede Anfrage, die diese spezifische Validierung nicht besteht. Fügen Sie Validierungen für Eingabetypen, Formate und Länge ein. Akzeptieren Sie nur bestimmte HTTP-Methoden für bestimmte Endpunkte und fügen Sie Zeitstempel für Ihre Anfragen ein, so dass nur die Anfragen akzeptiert werden, die in einem bestimmten Zeitrahmen gestellt werden. Dies verhindert einige der Brute-Force-Angriffe, die Ihre Server möglicherweise treffen.

Sie können die Sicherheit Ihrer Authentifizierung einen Schritt weiter bringen, indem Sie das Authentifizierungs-Framework OAuth 2.0 implementieren. Mit Hilfe von Anwendungen von Drittanbietern können Sie eine sicherere Umgebung für Ihre Benutzer schaffen.

Geben Sie niemals sensible Informationen wie Benutzernamen, Kennwörter, API-Schlüssel usw. in URLs preis. Wenn Sie diese Informationen wirklich übertragen müssen, indem Sie sie in der URL speichern, serialisieren Sie sie so, dass nur der Rechner, mit dem Sie kommunizieren müssen, die empfangenen Daten versteht.

3. Wählen Sie das richtige Datenformat zur Unterstützung

Die API ist wie eine Brücke zwischen dem Server und dem Client. Deshalb sollten wir die Daten in einem für beide Parteien geeigneten Format übertragen. Diese Wahl wird die Geschwindigkeit und den Erfolg der Anfragen beeinflussen.

Einige der am häufigsten verwendeten Datenformate bei der Erstellung einer API sind direkte Daten, Feed-Daten und Datenbankdatenformate.

Direkte Datenformate sind die beste Option, wenn Sie versuchen, mit anderen APIs zu interagieren. Einige der am häufigsten verwendeten Formate sind JSON, YAML und XML.

Feed-Datenformate werden in der Regel verwendet, um Aktualisierungen von Servern oder Front-End-Webanwendungen zu veröffentlichen und die Nutzer über die vorgenommenen Änderungen zu informieren. Wie Sie wahrscheinlich schon erraten haben, werden diese Formate am häufigsten für soziale Medien, Blogs oder Video-Sharing-Plattformen verwendet.

In den meisten Fällen werden Datenbankdatenformate verwendet, um Daten zwischen verschiedenen Datenbanken oder zwischen anderen Anwendungen und Datenbanken zu manipulieren. SQL und CSV sind zwei der am häufigsten verwendeten Formate in dieser Kategorie.

4. Paginierung verwenden

Wenn die API, die Sie und Ihr Team entwickeln, große Datenmengen zurückgibt, könnte es eine gute Idee sein, eine Paginierung zu implementieren. Wir sollten immer Situationen vermeiden, in denen der Nutzer die Möglichkeit hat, den Dienst zum Absturz zu bringen.

Wir empfehlen, eine Standardgrenze für die zurückgegebenen Daten und Parameter wie Limit und Offset zu verwenden, etwa so: /users?limit=30&offset=60.

Die Paginierung bietet auch eine großartige Möglichkeit, Ihren Nutzern bei der Entscheidungsfindung zu helfen und beseitigt das bereits verachtete unendliche Scrollen.

5. Erstellen Sie Versionen für jede wichtige Funktion

Der Prozess der Versionierung einer API hilft den Entwicklern, die Kontrolle über die Anwendung zu behalten. Man kann nie wissen, wie sich ein neues Update auf die Benutzerfreundlichkeit eines jeden Nutzers auswirkt. Versuchen Sie immer, die alten Versionen Ihrer API zu sichern, auch wenn Sie sie komplett ändern.

Sehen wir uns einige Beispiele dafür an, wie eine API versioniert werden kann:

Geben Sie die Versionsnummer direkt in die URL der API ein: api.example.com/v1/users
Legen Sie benutzerdefinierte Header fest, die die Versionsnummer der API enthalten: curl -H "API-version: 1.0 " https://api.example.com/users
Passen Sie den Accept-Header so an, dass er die Versionsnummer der API enthält: curl -H "Accept: application/vnd.example.v1+json " https://api.example.com/users
Fügen Sie die Versionsnummer als Abfrageparameter hinzu: https://api.example.com/users?version=1

6. Richtige HTTP-Methoden und -Codes verwenden

RESTful APIs verfügen über vier Methoden, um anzugeben, was Entwickler mit den übergebenen Daten tun werden.

Obwohl es logisch erscheinen mag, neigen Entwickler dazu, nur 2 der nachfolgend vorgestellten HTTP-Methoden zu verwenden. Es ist eine perfekte Praxis, jede von ihnen jedes Mal zu verwenden, wenn die Situation es erfordert.

GET - Verwenden Sie diese Methode jedes Mal, wenn Sie eine Ressource oder eine Sammlung von Ressourcen abrufen müssen.
POST - Entwickler sollten es jedes Mal verwenden, wenn sie eine neue Ressource oder eine Sammlung von Ressourcen erstellen müssen.
PUT - Diese Methode wird verwendet, um bestimmte Informationen zu aktualisieren.
DELETE - Diese Funktion ist ziemlich selbsterklärend. Es hilft uns, vorhandene Ressourcen oder die Sammlung von Ressourcen zu löschen.

Genauso wie die Entwickler es vorziehen, nur zwei der zuvor genannten HTTP-Codes zu verwenden, verwenden sie meistens auch nur zwei HTTP-Codes. Dies kann ihnen selbst und allen Entwicklern, die in Zukunft an dem Projekt arbeiten werden, viel Kopfzerbrechen bereiten.

200 OK - Dies ist der häufigste Code, über den wir als Entwickler stolpern. Oder zumindest hoffen wir, dass wir das tun. Er wird uns angezeigt, wenn ein Vorgang erfolgreich durchgeführt wurde.
201 CREATED - Die zuvor vorgestellte POST-Methode geht Hand in Hand mit diesem HTTP-Code, da er den Client darüber informieren soll, dass die Ressource erfolgreich erstellt wurde.
400 BAD REQUEST - Dies ist der HTTP-Code, der erscheint, wenn eine Anfrage nicht erfolgreich durchgeführt werden konnte.
401 UNAUTHORIZED - Wenn wir den Zugriff eines Benutzers auf einen Teil unserer Anwendung beschränken müssen, sollte dies der HTTP-Code sein, den wir zusammen mit der Fehlermeldung senden.
404 NOT FOUND - Der häufigste HTTP-Code im gesamten Internet. Selbst Menschen, die keine Software-Entwicklung studiert haben, wissen, dass der HTTP-Code 404 bedeutet, dass die Ressourcen nicht gefunden wurden.
500 INTERNER SERVERFEHLER - Dieser Fehler sollte immer dann auftreten, wenn der Server nicht antwortet.

Wie Sie sehen können, sind alle HTTP-Codes ziemlich selbsterklärend. Die Verwendung jedes einzelnen von ihnen, wenn es die Situation erfordert, kann auf lange Sicht viel Zeit sparen helfen.

7. Stellen Sie sicher, dass die Fehlermeldungen eindeutig sind

Wir alle wissen, wie frustrierend es ist, wenn ein Fehler auftritt und die Meldung nur vage ist. Nicht nur, dass der Dienst nicht funktioniert, wir müssen jetzt auch noch herausfinden, woher das Problem kommt.

Wir müssen die richtigen Fehlermeldungen und den eindeutigsten HTTP-Fehlercode ausgeben, um diese Verwirrung zu beseitigen.

Wenn zum Beispiel ein Nutzer ein neues Konto anlegen möchte, die E-Mail aber bereits auf der Plattform verwendet wird, sollten wir einen 400 HTTP-Code mit der Meldung "E-Mail bereits vorhanden" zurückgeben. Auf diese Weise vermeiden wir eine beträchtliche Anzahl von Anfragen, da der Benutzer weiß, worum es geht, und die Registrierung nicht erzwingen wird.

Wie sieht also eine effektive REST-API aus?

Damit sind wir am Ende einer vollständigen Liste von Tipps angelangt. Dies sind nur einige der Methoden, die Sie verwenden können, um eine sicherere REST-API zu erstellen. Natürlich gibt es noch viel mehr, aber wenn Sie nur die oben vorgestellten verwenden, sind Sie wahrscheinlich den meisten, die bereits erstellt wurden, voraus.

Wenn Sie jedoch nicht die Zeit und Geduld haben, eine API für Ihre Web-Scraping-Projekte zu entwickeln, warum nicht in etwas Fertiges investieren? Unser Team hat sich die Mühe gemacht, eine der sichersten und benutzerfreundlichsten Web-Scraping-APIs zu entwickeln. Dies sind nur einige der wichtigsten Grundsätze, die sie angewandt haben, um sicherzustellen, dass es niemals zu Datenverletzungen oder API-Ausfallzeiten kommen wird.

Wenn Sie es ausprobieren möchten, können Sie 1000 API-Aufrufe erhalten, indem Sie ein kostenloses Konto erstellen und eine der erfolgreichsten Web Scraping APIs testen.

Starten Sie jetzt Ihre Web Scraping Reise!