Im letzten Artikel dieser Reihe erfahren Sie mehr über REST-API-Empfehlungen und Entwicklungsbeispiele von Java und Spring Web Services.
Bei der Entwicklung einer guten REST-API ist es wichtig, über gute Microservices zu verfügen.
Wie entwickeln Sie Ihre REST-API? Was sind die Best Practices?
Sie werden lernen:
- Wie entwickle ich eine gute REST-API?
- Was muss ich bei der Entwicklung einer REST-API beachten?
- Was sind die Best Practices für die Entwicklung von RESTful-Webdiensten?
REST-API
Dies ist der letzte Artikel in einer Reihe von Artikeln über die REST-API:
Verwenden Sie den Consumer First Approach
Wer wird Ihren Service nutzen? Verbraucherdienstleistungen.
Betrachten Sie den Service aus Sicht des Verbrauchers?
- Kann Ihr Verbraucher Ihre API verstehen, wenn Sie eine API entwickeln?
- Wenn Sie Ihre Ressourcen veröffentlichen, kann der Verbraucher sie finden und darauf zugreifen?
- Kann der Verbraucher Ihre URIs verstehen?
- Welche Art von Service bieten Sie an?
- Handelt es sich um eine mobile Anwendung oder eine Webanwendung?
- Welche Verbraucher erwarten Sie und können sich diese Verbrauchertypen in Zukunft ändern?
- Wenn Sie so etwas wie HATEOAS implementieren, überlegen Sie, wie Ihre Kunden es verwenden werden, bevor Sie es implementieren.
- Das Wichtigste ist eine hervorragende Dokumentation
- Erleichtern Sie Ihren Kunden das Sparen von Zeit.
- Je mehr Konsumenten alleine tun können, desto weniger Arbeit für Sie.
Wenn Sie eine Diskussion oder einen Service-Review haben, stellen Sie die Kundenanforderungen an erster Stelle.
Nutzen Sie den Contract First Approach
Was ist ein Vertrag?
Der Ersteller des Webdienstes gilt als
Dienstleister . Eine Anwendung, die einen Webdienst verwendet, ist ein
Benutzer des Dienstes .
Ein Vertrag ist eine Vereinbarung zwischen einem Anbieter und einem Verbraucher über eine Dienstleistung.
Um den Dienst korrekt zu nutzen, muss der Verbraucher des Dienstes den Vertrag vollständig verstehen. Der Vertrag enthält Einzelheiten zu vielen Aspekten der Dienstleistung, wie z.
- Wie rufe ich einen Webservice auf?
- Welche Art von Transport wird verwendet?
- Was sind die Anfrage- und Antwortstrukturen?
Dies wird auch als
Service-Definition bezeichnet .
In der Methode "Vertrag zuerst" definieren Sie zuerst einen Servicevertrag und implementieren dann nur den Service.
Vertrag zuerst mit WSDL
Wenn Sie beispielsweise SOAP-Webdienste definieren, verwenden Sie WSDL, um den Vertrag zu definieren.
Die WSDL bestimmt die Service-Endpunkte, die von Ihnen veröffentlichten Vorgänge sowie die Anforderungs- und Antwortstrukturen.
Erster Vertrag mit Swagger / Open API
Wenn Sie RESTful-Webdienste verwenden, ist Swagger ein beliebtes Tool zur Dokumentation Ihrer Webdienste.
Mit Swagger können Sie bestimmen, welche Ressourcen Sie als Teil Ihrer API bereitstellen. Es enthält die Details der einzelnen Vorgänge, z. B. ob XML, JSON oder beides verwendet wird. Eine Antwortskizze ist auch da.
Es enthält auch detaillierte Informationen zu den unterstützten Antwortcodes. Sie können auch sehen, dass diese bestimmte Ressource
/ jpa / users :
unterstützt den GET-Betrieb. Tatsächlich unterstützt es auch die POST-Operation:
Wenn diese Ressource verfügbar ist, lautet das Antwortschema:
Die Definition des Benutzerobjekts ist in der Swagger-Vereinbarung enthalten als:
Es enthält die folgenden Attribute:
birthDate ,
id ,
name und eine Reihe von Nachrichtenbeiträgen. Einige Felder enthalten auch ein Beschreibungsfeld.
Im ersten Ansatz des Vertrags erstellen Sie vor der Implementierung des Service manuell oder mithilfe der Anwendung die von Swagger erstellte Definition.
Vorteile des Contract First Approach
Mit dem Contract First Approach denken Sie über Ihre Kunden nach und wie diese diesen Service nutzen können. Sie sind anfangs nicht besorgt über Implementierungsdetails.
Wenn Sie in einem frühen Stadium großen Wert auf die Implementierung legen, gehen technische Details in die Definition Ihrer Dienstleistung ein.
Sie müssen sicherstellen, dass die Definition Ihres Dienstes nicht von der von Ihnen verwendeten Plattform abhängt, sei es Java, .NET oder eine andere.
Definieren Sie Organisationsstandards für die REST-API
Eine wichtige Richtlinie für Ihre organisatorischen Standards ist YARAS.
YARAS steht für einen
weiteren RESTful API Standard . YARAS bietet die Standards, Richtlinien und Konventionen, die bei der Entwicklung von RESTful-Webdiensten beachtet werden müssen. Er gibt Empfehlungen für die folgenden Dinge:
- Wie sollten Sie Ihre Dienste benennen?
- Wie Sie Ihre Anfrage und Antwort strukturieren sollen
- Wie Sie Filter-, Sortier-, Paginierungs- und andere Aktionen implementieren sollten
- Wie sollten Sie die Versionierung angehen?
- Wie müssen Sie an die API-Dokumentation herangehen?
Einheitlicher Ansatz für die Serviceentwicklung
Sie müssen viele komplexe Probleme lösen, bevor Sie mit dem Entwurf von RESTful-Webdiensten beginnen. All dies müssen Sie herausfinden.
Die Führung Ihres Unternehmens möchte nicht, dass Teams, die mit unterschiedlichen Ressourcen umgehen, unterschiedliche Ansätze für diese Dinge verfolgen.
Es ist beispielsweise unerwünscht, dass Team-A die Versionierung auf der Grundlage von Abfrageparametern organisiert und Team-B die Versionierung auf der Grundlage von URIs verwendet.
Daher ist es wichtig, dass Sie die organisatorischen Standards für Ihren Ansatz zu RESTful-Webdiensten klar definiert haben.
Anpassung von YARAS AN organisatorische Bedürfnisse
Das Gute an YARAS ist, dass es an unternehmensspezifische Anforderungen angepasst werden kann. Zum Beispiel können Sie:
- Konfigurieren Sie, wie die Anforderungs- und Antwortkörper aussehen sollen.
- Wählen Sie ein bestimmtes Versionskontrollsystem
Da YARAS ziemlich umfassend abgedeckt ist, können Sie sicher sein, dass Sie keine wichtige Entscheidung verpasst haben.
Auswählen eines Standard-REST-API-Frameworks für Unternehmen
Typische Frameworks zum Erstellen von REST-fähigen Webdiensten in der Java-Welt sind Spring MVC, Spring REST und JAX-RS.
Wenn Sie ein organisationsspezifisches Framework / einen Archetyp / eine Referenzanwendung erstellen, das / die sich auf der bevorzugten REST-API-Plattform an gängigen Organisationsstandards orientiert, können Teams problemlos gemeinsame Standards einhalten.
Typische Merkmale sind:
- Anfrage- und Antwortstrukturen
- Fehlerbehandlung
- Filterung
- Suche
- Versionierung
- Unterstützung für falsche Antworten
- Hass
Das Standardframework bietet einen einheitlichen Ansatz für das Entwerfen und Implementieren von Diensten im gesamten Unternehmen.
Dezentrale REST-API-Verwaltung
Erstellen Sie eine Expertengruppe aus den Teams, die die REST-API erstellen, und bilden Sie ein Management-Team. Das Team ist verantwortlich für
- Verbesserung der REST-API-Standards
- Erstellen / Entwerfen Ihres REST-API-Frameworks
Weit verbreitete Verwendung von HTTP
Wenn Sie an RESTful-Webdienste denken, denken Sie an HTTP.
HTTP bietet alle Funktionen, mit denen Sie hervorragende Webdienste erstellen können.
Verwenden Sie die richtigen HTTP-Anforderungsmethoden
Denken Sie an die HTTP-Anforderungsmethoden, die Sie verwenden müssen. Wenn Sie eine Operation implementieren möchten, bestimmen Sie die Ressource, für die sie ausgeführt werden soll, und suchen Sie dann die entsprechende HTTP-Anforderungsmethode. Rufen Sie Details ab, erstellen Sie etwas, aktualisieren Sie etwas Bestehendes oder löschen Sie ein Bestehendes?
HTTP-Methoden verwenden:
- GET zu bekommen
- POST zu erstellen
- PUT zu aktualisieren
- LÖSCHEN zum Löschen
- PATCH für teilweise Updates
Verwenden Sie den entsprechenden HTTP-Antwortstatus
Stellen Sie beim Ausführen des Vorgangs sicher, dass Sie den richtigen Antwortstatus zurückgeben.
Wenn beispielsweise eine bestimmte Ressource nicht gefunden wird, darf keine Serverausnahme ausgelöst werden. Senden Sie stattdessen den entsprechenden Antwortcode in einer Antwortnachricht, z. B.
404 .
Wenn es wirklich eine Serverausnahme gibt, senden Sie den Code
500 zurück.
Wenn die Validierung fehlschlägt, senden Sie den Code für die ungültige Anforderung.
Leistung im Fokus
Jede Ressource kann mehrere Darstellungen haben - im XML- oder JSON-Format. Der Dienstverbraucher kann die Präsentation seiner Wahl wählen.
Der Service gibt 3 Benutzer zurück, wenn wir eine GET-Anfrage senden. In diesem Fall erhalten wir die JSON-Darstellung der Ressource
/ users .
Wenn der Verbraucher keine bevorzugte Ansicht angibt, verwenden wir JSON.
Der Consumer kann einen Accept-Header senden, um die Ansicht anzugeben.
Der Antworttext hat jetzt XML-Inhalt:
Verwenden Sie den Plural
Verwenden Sie immer den Plural, wenn Sie Ressourcen benennen.
Schauen wir uns ein einfaches Beispiel an. Angenommen, wir haben einen Dienst, der eine Benutzerressource hostet. Im Folgenden wird beschrieben, wie Sie darauf zugreifen können:
- Benutzer erstellen: POST / Benutzer
- Benutzer löschen : DELETE / users / 1
- Holen Sie sich alle Benutzer: GET / users
- Holen Sie sich einen Benutzer: GET / users / 1
Durch die Bevorzugung mehrerer Benutzer gegenüber dem Benutzer wird der URI besser lesbar.
- Wenn wir beispielsweise / user anstelle von / users verwenden , um abzurufen , gibt GET / user die richtige Nachricht nicht an den Leser weiter.
Erstellen Sie eine gute Dokumentation
Die Verbraucher müssen verstehen, wie sie den Dienst optimal nutzen können, und der beste Weg, ihnen zu helfen, besteht darin, eine gute Dokumentation zu erstellen.
SOAP-Webdienste können WSDL-Funktionalität verwenden, während RESTful-Webdienste Swagger-Optionen (jetzt der Open API-Dokumentationsstandard) aufweisen.
Die Auswahl eines Formats ist nur ein Teil der Erstellung einer guten Dokumentation. Wichtig ist auch die Bereitstellung der richtigen Informationsmenge, um dem Verbraucher zu helfen.
Die Dokumentation sollte vollständig sein und folgende Punkte enthalten:
- Was ist eine Anfrage- und Antwortstruktur?
- Wie soll sich ein Verbraucher authentifizieren?
- Was sind die Einsatzgrenzen?
- Geben Sie alle Arten von Antwortnachrichten und die entsprechenden Statuscodes an, die vom Service erwartet werden können.
Erstellen Sie ein gemeinsames REST-API-Dokumentationsportal
Es wäre hilfreich, ein gemeinsames REST-API-Dokumentationsportal für die gesamte Organisation zu haben. Schauen Sie sich ein solches Portal an:
Ein solches Portal fasst alle in der Organisation verfügbaren Ressourcen zusammen. Eine Benutzeroberfläche wie die Swagger-Benutzeroberfläche bietet zusätzliche Vorteile. Mit der Swagger-Benutzeroberfläche können Sie die Dokumentation detaillierter anzeigen:
Dies kann auch von nicht technischen Benutzern verwendet werden. Die hier bereitgestellten Informationen umfassen:
- Erwartetes Antwortformat
- Inhaltstyp
- Unterstützte Antwortcodes
Das Dokumentationsformat im Stil einer Live-Anfrage / Antwort kann ebenfalls von Interesse sein.
Versionsunterstützung
Die Versionskontrolle ist für einen Webservice mit einer hohen Komplexität verbunden. Es ist sehr schwierig, mehrere verschiedene Versionen desselben Webdienstes zu verwalten. Versuchen Sie dies nach Möglichkeit zu vermeiden.
In bestimmten Szenarien ist jedoch eine Versionskontrolle unumgänglich.
Beginnen wir mit einem Beispielservice. Angenommen, wir haben anfangs einen Service mit der
PersonV1- Klasse wie folgt definiert:
Diese Version der Klasse berücksichtigt nicht, dass ein Name viele Unterabschnitte haben kann, z. B. Vor- und Nachname. Überprüfen Sie dies heraus:
Die zweite Version der Quellklasse wurde aktualisiert, um diese Anomalie zu beheben:
Wir können den gesamten Service nicht sofort auf die Nutzung von
PersonV2 übertragen ! Möglicherweise warten andere Verbraucher auf Antworten im
PersonV1- Format.
Hier ist eine Versionskontrolle erforderlich.
Lassen Sie uns nun die Optionen betrachten, die wir für die Versionskontrolle dieser beiden Ressourcen haben.
Verwendung verschiedener URIs
Wir haben eine Option - verschiedene URIs für diese verschiedenen Ressourcen zu verwenden. Im folgenden Prüfungscode verwenden wir die URIs
v1 / person und
v2 / person , um sie zu unterscheiden:
Wenn Sie eine GET-Anforderung für die Ressource
v1 / person ausführen:
Sie erhalten Informationen entsprechend
v1 . Für eine andere Ressource:
Verwenden des Abfrageparameters
Die zweite Versionskontrollmethode verwendet den Abfrageparameter:
Wenn wir in der URI
/ person / param den Parameter mit
version = 1 senden, geben wir eine Ressource vom Typ
PersonV1 zurück :
Für denselben URI gibt der Parameter mit
Version = 2 eine Ressource vom Typ
PersonV2 zurück :
Diese Methode wird als Versionierung mit Abfrageparametern bezeichnet.
Header verwenden (Header)
Eine andere Möglichkeit ist die Versionskontrolle durch Angabe eines Titels. Hier verwenden wir einen Header namens
X-API-VERSION und markieren den URI als
/ person / header . Wenn der Header-Wert
1 ist , wird eine Ressource vom Typ
PersonV1 zurückgegeben :
Wenn sein Wert
2 ist , wird eine Ressource vom Typ
PersonV2 abgerufen:
Wir verwenden das Attribut im Anforderungsheader, um die Versionskontrolle für uns durchzuführen.
Accept Header verwenden
Die letzte Methode zum Erstellen von Versionen verwendet den Accept Header. Wenn der Consumer die ersten Versionsinformationen in den Accept-Header der GET-Anforderung aufnimmt, wird die folgende Ressource zurückgegeben:
Andernfalls wird eine Ressource vom Typ
PersonV2 zurückgegeben :
Diese Versionskontrollmethode wird als
Accept Header Versioning oder
Media Type Versioning bezeichnet , da MIME-Typen normalerweise den Inhalt des Accept-Headers darstellen.
Vergleich der Versionskontrollmethoden
Bisher haben wir vier Arten von Methoden in Versionen gesehen:
- Verwendung verschiedener URIs
- Verwenden des Abfrageparameters
- Verwendung von Header
- Verwenden von Kopfzeile / Medientyp akzeptieren
Welches ist das Beste? Die Wahrheit ist, dass es keine einzige Antwort auf diese Frage gibt. Tatsache ist, dass verschiedene Internetgiganten unterschiedliche Arten von Versionen unterstützen.
- Verwendung verschiedener URIs - Twitter
- Verwenden von Abfrageparametern - Amazon
- Verwenden eines Headers - Microsoft
- Verwenden von Accept Header / Media Type - GitHub
Sie müssen diese vier Optionen entsprechend Ihren spezifischen Anforderungen bewerten. Es gibt eine Reihe wichtiger Faktoren zu berücksichtigen:
- URI-Verschmutzung : Durch die Steuerung von Versionen mithilfe von URIs und Abfrageparametern wird der URI-Bereich verschmutzt. Dies liegt daran, dass wir den Hauptzeichenfolgen der URI Präfixe und Suffixe hinzufügen. Die Versionskontrolle über einen Header vermeidet dies.
- Missbrauch von HTTP-Headern . Bei der Versionskontrolle mit Headern und Medientyp werden HTTP-Header missbraucht, da sie ursprünglich nicht für die Versionskontrolle vorgesehen waren.
- Caching : Eine Ressource wird durch ihren URI identifiziert. Wenn Sie jedoch keinen URI zum Ermitteln der Version verwenden, sondern einen auf Kopfzeilen basierenden Mechanismus verwenden, können die Versionsinformationen nicht zwischengespeichert werden. Wenn HTTP-Caching für Sie wichtig ist, verwenden Sie die Versionskontrolle basierend auf einem URI oder Anforderungsparameter.
- Ausführbarkeit von Browser-Anfragen : Für die Versionierung nach Titel und Medientyp sind Tools wie Postman erforderlich. Wenn Service-Consumer jedoch technisch nicht versiert sind, ist es vorzuziehen, die Versionskontrolle auf der Grundlage eines URI oder eines Abfrageparameters zu verwenden.
- API-Dokumentation : Sie müssen auch darüber nachdenken, wie Sie Ihre APIs dokumentieren möchten. Die auf dem URI und dem Abfrageparameter basierende Versionierung ist einfacher zu dokumentieren als die beiden anderen Arten der Versionskontrolle.
Verstehen Sie, dass es keine einzige ideale Lösung gibt!
Denken Sie an die Fehlerbehandlung
Wenn ein Verbraucher eine Anfrage an einen Dienst sendet, ist es wichtig, dass er die richtige Antwort erhält. Wenn etwas schief geht, ist es wichtig, eine angemessene Antwort zu senden.
Wenn ein Verbraucher eine nicht vorhandene Ressource anfordert
Wenn wir eine GET-Anfrage senden, um nach einem vorhandenen Benutzer zu suchen, erhalten wir die folgende Antwort:
Wenn Sie einen nicht existierenden Benutzer suchen:
Sie erhalten den Status
404 Nicht gefunden . Dies ist eine gute Fehlerbehandlung, da hiermit korrekt festgestellt wird, dass die Ressource nicht gefunden wurde, und kein Serverfehler zurückgegeben wird.
Senden wir nun eine GET-Anfrage an eine nicht vorhandene URI:
Wie Sie sehen, erhalten Sie den Antwortstatus
404 Nicht gefunden . Eine ungültige URL weist auf eine nicht vorhandene Ressource hin.
Wichtige Antwortstatus
- 200 - Erfolg
- 404 - Ressource nicht gefunden
- 400 - ungültige Anforderung (z. B. Validierungsfehler)
- 201 - erstellt
- 401 - nicht autorisiert (falls Authentifizierung fehlschlägt)
- 500 - Serverfehler
Fehlerdetails im Antworttext
Dies ist hilfreich, wenn Sie bei der Entwicklung Ihres Service eine Standardausnahmestruktur verwenden.
Für bestimmte Fehler können bestimmte Antwortstrukturen an den Verbraucher zurückgegeben werden, und dies kann der Standard in der gesamten Organisation sein. Stellen Sie sicher, dass die Fehlerantwort auch für Verbraucher ohne Verwirrung lesbar ist.
Verwenden der Swagger- oder Open API-Dokumentation
Swagger bietet eines der beliebtesten Dokumentationsformate für RESTful-Webdienste. Heute wird es von verschiedenen Organisationen unterstützt und in einer Vielzahl von Diensten eingesetzt. Hier betrachten wir zwei Hauptaspekte von Swagger:
- Swagger-Dokumentationsformat
- Swagger-Benutzeroberfläche, mit der Sie die Swagger-Dokumentation auf visuell bequeme Weise anzeigen können
Swagger-Dokumentation
Schauen Sie sich folgenden Swagger JSON an:
Auf der obersten Ebene sieht dies der Definition von WSDL sehr ähnlich. Es hat mehrere wichtige Attribute:
- Host : Wo befindet sich der Service?
- basePath : Der Pfad, in dem sich der Dienst befindet
- verbraucht : welche Anfragen werden angenommen
- Erzeugt : Welche Arten von Antworten werden generiert
- Pfade : Verschiedene Ressourcen verfügbar In diesem Fall enthält die Liste verschiedene Arten von Ressourcen:
Wenn Sie sich die Swagger-Dokumentation ansehen, können Sie schnell verfügbare Ressourcen, unterstützte Vorgänge und Vorgänge im Zusammenhang mit den einzelnen Ressourcen identifizieren:
Die Ressource
/ users unterstützt
GET- und
POST- Vorgänge. Für
GET werden die unterstützten Anforderungs- und Antworttypen angezeigt. Sie sehen auch verschiedene Arten von Antworten:
Beachten Sie, dass für Antwort
200 die Schaltung auch als
Benutzerarray bezeichnet wird.
Der Benutzer ist Teil des
Definitionsabschnitts am Ende des Dokuments:
Swagger ist völlig unabhängig von der Technologie, mit der Sie einen RESTful-Webdienst implementieren. Oh, alles basiert auf JSON.
Einführung in die Swagger-Benutzeroberfläche
Die Swagger-Benutzeroberfläche ist eine großartige Benutzeroberfläche, die sehr nützlich ist, um die Swagger-Dokumentation für den RESTful-Webdienst zu visualisieren.
Schauen Sie sich den Screenshot unten an:
Bitte beachten Sie, dass wir eine bestimmte Version des Webdienstes ausgewählt haben, um dessen Dokumentation anzuzeigen. Hier ist der gleiche Bildschirm im Detail:
Wenn wir zur Homepage gehen, werden die aufgelisteten Ressourcen beschrieben:
Sie können auch die für Ressourcen-URLs unterstützten Operationen sehen:
Wenn Sie auf die GET-Operation einer bestimmten Ressource klicken, erhalten Sie deren Details:
Sie können das Schema sehen Modelle werden visuell beschrieben. Die Attribute birthDate , id , links , name und posts werden ebenfalls angezeigt. Sie können auch eine Beispielabfrage ausführen und die Antwort anzeigen:
Swagger Tools verwenden (Open API Standard)
Das Tolle an Swagger sind die vielen Tools, die es gibt. Sehen Sie sich den folgenden Service an, den wir zuvor zur Erklärung der Versionskontrolle verwendet haben: Hier sehen Sie die automatisch generierte Dokumentation für diesen Service:
Swagger unterstützt sowohl den Contract-First-Ansatz als auch den Code-First-Ansatz.Zu diesem Thema gibt es ein Copyright - Video .Zusammenfassung
In diesem Artikel befassten wir uns mit bewährten Methoden zum Erstellen und Entwerfen von RESTful-Webdiensten.Zusätzliche Lektüre
Seien Sie der BESTE in Ihrer REST-API!REST-APIs entwickeln