Best Practices für die REST-API

REST wird zum gängigen Ansatz, um die Dienste der Außenwelt zugänglich zu machen. Der Grund für die Beliebtheit liegt in der Einfachheit, Benutzerfreundlichkeit, dem Zugriff über HTTP (auf REST kann über alle Protokolle zugegriffen werden, wird jedoch am häufigsten mit HTTP verwendet) usw. Es besteht ein weit verbreitetes Missverständnis, dass alle über das Netzwerk bereitgestellten Ressourcen berücksichtigt werden als REST, aber das ist nicht korrekt. In diesem Tutorial erkläre ich Ihnen einige der Best Practices, die Sie bei der Implementierung Ihrer eigenen REST-API immer beachten müssen.

Best Practices für das REST-API-Design

Ich würde gerne Ihre Erfahrungen als REST-API-Entwickler hören. Wenn Sie auf Best Practices gestoßen sind, die hier nicht erwähnt werden, teilen Sie uns diese bitte im Kommentarbereich mit.

  • Lesen Sie auch: REST vs. SOAP

Haftungsausschluss: Diese Best Practices halte ich aufgrund meiner bisherigen Erfahrungen für gut. Wenn Sie anderer Meinung sind, senden Sie mir gerne eine E-Mail, damit wir darüber diskutieren können.

Best Practices für das REST-API-Design

Hier ist die Liste der Best Practices, die in diesem Tutorial besprochen werden:

  • Endpunkte als Substantive, nicht als Verben
  • Verwenden Sie Pluralformen
  • Dokumentation
  • Versionieren Sie Ihre API
  • Paging
  • Verwenden Sie SSL
  • HTTP-Methoden
  • Verwenden Sie effektiv HTTP-Statuscodes
  • 1. Endpunkte als Substantive, nicht als Verben

    Eine der häufigsten Fehlpraktiken der REST-API-Entwickler ist die Verwendung von Verben zur Benennung der REST-Endpunkte. Dies ist jedoch keine bewährte Vorgehensweise. Sie müssen immer Substantive anstelle von Verben verwenden.

    Beispielszenario:

    Wir sind verpflichtet, REST-Webdienste zum Abrufen von Landwirten (Landwirten) in Indien bereitzustellen. Der Dienst sollte auch die Funktionalität implementieren, andere Details wie Einkommen, Name der Kulturpflanze, Adresse usw. abzurufen, die sich auf jeden Landwirt beziehen. Jedem Landwirt wird eine eindeutige ID zugewiesen.

    In ähnlicher Weise sollte es Dienste zur Offenlegung der Pflanzendetails und der Frage geben, welcher Landwirt sie angebaut hat.

    Beste Übung:

    Verfügen Sie über einen einzigen Endpunkt, der alle Vorgänge repräsentiert. Im folgenden Beispiel stellen wir nur einen Endpunkt /farmers für alle Vorgänge wie Abrufen, Hinzufügen, Aktualisieren und Löschen bereit. Die zugrunde liegenden Implementierungen verfügen über unterschiedliche HTTP-Methoden, die für die verschiedenen Vorgänge korrekt weitergeleitet werden. Weitere Details finden Sie im folgenden Abschnitt für HTTP-Methoden.

    • /Bauern
    • /Ernten

    Nicht empfohlen:

    Bitte vermeiden Sie die Verwendung der Verben oder Operationen in der Namenskonvention. Es wird empfohlen, den Vorgang innerhalb des Datenformats (JSON / XML / RAML) darzustellen oder die HTTP-Methoden zu verwenden. Verwenden Sie nicht die folgenden Dienstendpunkte:

    • /getFarmers
    • /updateFarmers
    • /deleteFarmers
    • /getCrops
    • /updateCrops
    • deleteCrops

    2. Verwenden Sie Pluralformen

    Verwenden Sie Pluralformen für die Benennung Ihrer REST-Dienste. Dies ist ein weiteres heißes Thema unter den REST-Designern, bei der Benennung der Dienste zwischen Plural- und Singularnomen zu wählen.

    Beste Übung:

    • /Bauern
    • /farmers/{farmer_id}
    • /Ernten
    • /crops/{crop_id}

    Nicht empfohlen:

    • /Bauer
    • /farmer/{farmer_id}

    Notiz: Obwohl ich erwähne, dass die Verwendung des Plural eine gute Praxis ist, sollten Sie aus irgendeinem Grund bei der Verwendung des Singulars dasselbe für alle Dienste befolgen. Verwechseln Sie nicht die Verwendung von Pluralformen und Singularformen. Deshalb behaupte ich nicht, dass es sich um eine schlechte Vorgehensweise handelt, sondern nur darum, dass sie nicht empfohlen wird. Bitte entscheiden Sie selbst, was für Ihre Bewerbung gut ist.

    3. Dokumentation

    Die Dokumentation der Softwareimplementierung ist die gängigste Praxis. Dies gilt auch für die REST-API-Implementierung. Wenn Sie eine nützliche Dokumentation schreiben, hilft sie anderen Programmierern beim Verständnis.

    • Lesen Sie auch: RESTful Web Service mit JAX-RS 2.0

    Die gebräuchlichste Methode zur Dokumentation von REST-APIs besteht darin, eine Dokumentation zu erstellen, die die API-Endpunkte auflistet und die Liste der für jeden Endpunkt zulässigen Vorgänge beschreibt. Es gibt zahlreiche Tools, mit denen Sie dies automatisiert durchführen können.

    Hier sind einige der Tools, die Ihnen bei der Dokumentation Ihrer REST-Dienste helfen können:

    Bitte teilen Sie Ihre Erfahrungen mit der Dokumentation Ihrer APIs.

    4. Versionieren Sie Ihre API

    Jede Software wird sich im Laufe der Zeit weiterentwickeln. Dies erfordert möglicherweise für jede größere Änderung der API eine andere Version. Wenn es um die REST-API-Version geht, ist sie eines der am meisten diskutierten Themen in der REST-Entwickler-Community.

    Es gibt zwei gängige Arten der Versionierung für die REST-API:

  • URI-Versionen
  • Medientypversionen
  • URI-Version

    Ein einfaches Beispiel, wie eine URI-Version aussehen würde:

    http://host/v2/farmers
    http://host/v1/farmers
    

    Im Folgenden sind die Hauptnachteile der Versionierung mithilfe von URI aufgeführt:

  • Dadurch werden die vorhandenen URIs beschädigt, alle Clients müssen auf den neuen URI aktualisieren
  • Dadurch wird die Anzahl der zu verwaltenden URI-Versionen erhöht, wodurch die HTTP-Caching-Größe des Clients zum Speichern mehrerer URI-Versionen erhöht wird. Das Hinzufügen einer größeren Anzahl doppelter URIs würde sich auf den Prozentsatz der Cache-Treffer auswirken und möglicherweise die Leistung Ihrer Anwendung verlangsamen.
  • Es ist äußerst unflexibel, wir können nicht einfach eine einzelne Ressource oder eine kleine Teilmenge von Ressourcen ändern.
  • Medientypversion

    Bei diesem Ansatz werden die Versionsdetails im Header jeder Anfrage gesendet. Wenn wir den Medientyp und die Sprache des URI ändern, führen wir eine Inhaltsverhandlung basierend auf dem Header durch. Dieser Ansatz ist die am meisten bevorzugte Option für die REST-API-Versionierung.
    Senden Sie stattdessen die generischen Medientypen wie application/jsondiese würden versioniert werden.
    Beispiel-Header-Informationen

    GET /account/5555 HTTP/1.1
    Accept: application/vnd.farmers.v1+json
    
    HTTP/1.1 200 OK
    Content-Type: application/vnd.farmers.v1+json
    

    Beim Medientyp-Versionierungsansatz hat der Client die Möglichkeit auszuwählen, welche Version er vom Server anfordern möchte. Dieser Ansatz sieht besser aus als der URI-Versionsansatz, es entsteht jedoch eine größere Komplexität beim Zwischenspeichern der Anforderungen mit unterschiedlichen Versionen, die über den Header weitergeleitet werden. Mit einfachen Worten: Wenn Client-Caches auf der Grundlage des URIs zwischengespeichert werden, ist es einfach, aber das Caching mit Schlüssel als Medientyp erhöht die Komplexität.

    5. Paging

    Das Senden großer Datenmengen über HTTP ist keine gute Idee. Dies wird sicherlich ein Leistungsproblem darstellen, da die Serialisierung großer JSON-Objekte teuer wird. Eine bewährte Vorgehensweise besteht darin, die Ergebnisse zu paginieren, anstatt alle Datensätze auf einmal zu senden. Bieten Sie die Möglichkeit, die Ergebnisse mithilfe von Weiter- oder Zurück-Links zu paginieren.

    Wenn Sie die Paginierung in Ihrer Anwendung verwenden, ist eine gute Möglichkeit, den Navigationslink anzuzeigen, die Verwendung von Link HTTP-Header-Option.

    Das Link von GitHub wird nützlich sein. Auch ein weiterer nützlicher Verknüpfung für die Verwendung von Link-Headern.

    6. Verwenden Sie SSL

    SSL ist ein Muss. Sie sollten immer SSL für Ihre REST-API implementieren. Der Zugriff auf Ihre Anwendung erfolgt von überall auf der Welt. Es gibt keine Garantie dafür, dass der Zugriff sicher erfolgt. Angesichts der zunehmenden Zahl von Cyber-Kriminalitätsvorfällen müssen wir unsere Anwendung ordnungsgemäß schützen.

    • Lesen Sie auch: So aktivieren Sie SSL auf dem JBoss-Server

    Authentifizierungsprotokolle nach Industriestandard tragen dazu bei, den Aufwand für die Sicherung Ihrer API zu reduzieren. Verwenden Sie nicht den grundlegenden Authentifizierungsmechanismus. Verwenden Sie entweder Oauth1.0a oder Oauth2 für die beste Sicherheit Ihrer Dienste. Ich würde Oauth2 aufgrund seiner neuesten Funktionen persönlich empfehlen.

    Wenn Sie uns etwas mitteilen möchten, schreiben Sie es bitte in den Kommentarbereich.

    7. Verwenden Sie HTTP-Methoden

    Das Zuordnen von Vorgängen zu HTTP-Methoden ist einfach, wenn Sie die Eigenschaften aller HTTP-Methoden kennen. In einem der vorherigen Abschnitte dieses Tutorials habe ich darauf bestanden, die HTTP-Methoden für Operationen zu verwenden, anstatt für jede Operation einen unterschiedlichen Benennungsdienst zu schreiben. Dieser Abschnitt befasst sich hauptsächlich mit dem Verhalten der einzelnen HTTP-Methoden.

    Im Folgenden sind die beiden Merkmale aufgeführt, die vor der Verwendung einer HTTP-Methode ermittelt werden müssen:

    • Sicherheit: Eine HTTP-Methode gilt als sicher, wenn der Aufruf dieser Methode den Status der Ressource nicht ändert. Wenn Sie beispielsweise Daten mit der GET-Methode abrufen, ist dies sicher, da diese Methode die Daten nicht im Back-End aktualisiert.
    • Idempotent: Wenn Sie bei jedem Aufruf derselben Ressource dieselbe Antwort erhalten, wird dies als idempotent bezeichnet. Wenn Sie beispielsweise versuchen, dieselben Daten im Back-End zu aktualisieren, ist die Antwort für jede Anfrage mit denselben Daten dieselbe.

    Nicht alle Methoden sind sicher oder idempotent. Hier ist die Liste der Methoden, die für REST-API-Aufrufe verwendet werden können, und welche Methoden sicher und idempotent sind.

    REST-HTTP-Methoden

    REST-HTTP-Methoden

    Hier finden Sie eine kurze Zusammenfassung der einzelnen Methoden und deren Verwendung:

    • ERHALTEN : Diese Methode ist sicher und idempotent. Es wird immer zum Abrufen der Informationen verwendet und hat keine Nebenwirkungen.
    • POST : Diese Methode ist weder sicher noch idempotent. Diese Methode wird am häufigsten zum Erstellen der Ressourcen verwendet.
    • SETZEN : Diese Methode ist idempotent. Aus diesem Grund kann man anstelle von POST diese Methode zum Aktualisieren der Ressourcen verwenden. Vermeiden Sie die Verwendung von POST zum Aktualisieren der Ressourcen.
    • LÖSCHEN : Wie der Name schon sagt, wird diese Methode zum Löschen der Ressourcen verwendet. Diese Methode ist jedoch nicht für alle Anforderungen idempotent.
    • OPTIONEN : Diese Methode wird nicht für Ressourcenmanipulationen verwendet. Es ist jedoch nützlich, wenn der Client die verschiedenen für eine Ressource unterstützten Methoden nicht kennt. Mit dieser Methode kann der Client die verschiedenen Darstellungen einer Ressource abrufen.
    • KOPF : Diese Methode wird zum Abfragen einer Ressource auf dem Server verwendet. Sie ist der GET-Methode sehr ähnlich, aber HEAD muss die Anfrage senden und die Antwort nur im Header erhalten. Gemäß der HTTP-Spezifikation sollte diese Methode keinen Body für Anfrage und Antwort verwenden.

    8. Nutzen Sie HTTP-Codes effektiv

    • Lesen Sie auch: Liste der HTTP-Statuscodes und Erläuterungen

    HTTP definiert verschiedene Statuscodes, um dem Client unterschiedliche Bedeutungen anzuzeigen. Ihre REST-API könnte effektiv alle verfügbaren HTTP-Codes nutzen, um dem Client dabei zu helfen, die Antwort entsprechend weiterzuleiten. Hier ist die Liste der HTTP-Statuscodes als Referenz:

    • 200 OK – Dies ist die Antwort auf erfolgreiches GET, PUT, PATCH oder DELETE. Dieser Code kann auch für einen POST verwendet werden, der nicht zu einer Erstellung führt.
    • 201 Erstellt – Dieser Statuscode ist eine Antwort auf einen POST, der zu einer Erstellung führt.
    • 204 Kein Inhalt – Dies ist eine Antwort auf eine erfolgreiche Anfrage, die keinen Text zurückgibt (wie eine DELETE-Anfrage).
    • 304 Nicht geändert – Verwenden Sie diesen Statuscode, wenn HTTP-Caching-Header im Spiel sind
    • 400 Bad Request – Dieser Statuscode zeigt an, dass die Anfrage fehlerhaft ist, beispielsweise wenn der Text nicht analysiert wird
    • 401 Nicht autorisiert – Wenn keine oder ungültige Authentifizierungsdaten angegeben werden. Auch nützlich, um ein Authentifizierungs-Popup auszulösen, wenn die API über einen Browser verwendet wird
    • 403 Verboten – Wenn die Authentifizierung erfolgreich war, der authentifizierte Benutzer jedoch keinen Zugriff auf die Ressource hat
    • 404 Nicht gefunden – Wenn eine nicht vorhandene Ressource angefordert wird
    • 405 Methode nicht zulässig – Wenn eine HTTP-Methode angefordert wird, die für den authentifizierten Benutzer nicht zulässig ist
    • 410 Gone – Dieser Statuscode zeigt an, dass die Ressource an diesem Endpunkt nicht mehr verfügbar ist. Nützlich als pauschale Antwort für alte API-Versionen
    • 415 Nicht unterstützter Medientyp – Wenn im Rahmen der Anfrage ein falscher Inhaltstyp angegeben wurde
    • 422 Nicht verarbeitbare Entität – Wird für Validierungsfehler verwendet
    • 429 Zu viele Anfragen – Wenn eine Anfrage aufgrund einer Ratenbegrenzung abgelehnt wird

    Zusammenfassung

    Ich hoffe, dass dieses Tutorial hilfreich ist, um zu verstehen, wie Sie Ihre REST-API entwerfen. Es gibt nichts, was als das Beste für das Universum bezeichnet werden kann und das auf das API-Design anwendbar ist. Hier sind die Best Practices zusammengestellt, die auf meinen Erfahrungen und Diskussionen mit Freunden basieren, die an den REST-Webdienstanwendungen gearbeitet haben.

    Wenn Sie intensiv am REST-API-Design gearbeitet haben und das Gefühl haben, dass dieses Tutorial für Sie keinen Sinn ergibt :), freue ich mich über Ihr Feedback. Ich würde diesen Bereich gerne mit bewährteren Techniken aktualisieren, um die beste API für Ihre Anwendung zu entwerfen.

    Viel Spaß beim Lesen und viel Spaß :). Vielen Dank für Ihren Besuch auf meinem Blog.

    Kommentar verfassen

    Deine E-Mail-Adresse wird nicht veröffentlicht. Erforderliche Felder sind mit * markiert

    Nach oben scrollen