REST-API - Woher weiß der Client, was eine gültige Nutzlast an die Ressource senden soll?
Eines der Ziele der REST-API-Architektur ist die Entkopplung von Client und Server.
Eine der Fragen, auf die ich bei der Planung einer REST-API gestoßen bin, ist: "Woher weiß der Client, was eine gültige Nutzlast für POST-Methoden ist?"
Irgendwie muss die API mit der UI kommunizieren, was eine gültige Nutzlast für die POST-Methode einer bestimmten Ressource ist. Ansonsten sind wir hier wieder zurück, abhängig vom Out-of-Band-Wissen, das notwendig ist, um mit einer API zu arbeiten, und wir sind wieder eng miteinander verbunden.
Ich hatte also die Idee, dass die API-Antwort für ein GET für eine Ressource eine Spezifikation zum Konstruieren einer gültigen Nutzlast für die POST-Methode für diese Ressource bereitstellen würde. Dazu gehören Feldnamen, Datentyp, maximale Länge usw.
Dieser Typ hat eine ähnliche Idee .
Was ist der richtige Umgang damit? Müssen sich die meisten Leute nur auf Out-of-Band-Informationen verlassen? Was machen Menschen in der realen Welt mit diesem Problem?
BEARBEITEN
Etwas, das ich zur Lösung dieses Problems entwickelt habe, ist im folgenden Sequenzdiagramm dargestellt:
Der Client und der api-Dienst sind getrennt. Der Kunde weiß:
- Einstiegspunkt
- Wie navigiere ich über die Hypermedia API?
Folgendes geschieht:
- Jemand (Benutzer) fordert die Registrierungsseite vom Client an
- Der Client fordert den Einstiegspunkt von der API an und empfängt alle Hypermedia-Links mit entsprechenden Metadaten, um sie legal zu durchlaufen.
- Der Client erstellt das Registrierungsformular basierend auf den Metadaten, die mit der Registrierungs-Hypermedia-POST-Methode verknüpft sind.
- Der Benutzer füllt das Formular aus und reicht es ein.
- Client sendet POST an die API mit den korrekten Daten und alles ist gut.
Keine Magie / Meta-Ressourcen, keine Notwendigkeit, eine Methode für die Metadaten zu verwenden. Alles wird von der API bereitgestellt.
Gedanken?
3 Antworten
Die meisten Menschen verlassen sich auf Out-of-Band-Informationen. Dies ist normalerweise in Ordnung, da die meisten Clients nicht dynamisch, sondern statisch erstellt werden. Sie beruhen auf bekannten Teilen der API und sind nicht HATEOAS-gesteuert.
Wenn Sie einen metadatengesteuerten Client entwickeln oder unterstützen wollen, dann müssen Sie ein Schema für die Bereitstellung dieser Informationen erstellen. Die Implementierung, mit der Sie verbunden sind, scheint nach einem kurzen Überspringen angemessen zu sein. Beachten Sie, dass Sie das Problem nur verschoben haben. Clients müssen immer noch wissen, wie die Informationen in den Metadatenantworten zu interpretieren sind.
Sie haben Recht, der Kunde sollte die Semantik der Links in der Antwort verstehen und die richtige auswählen, um sein Ziel zu erreichen. Der Client ist an die Semantik gekoppelt, die die API zu diesem Zweck bereitstellt, und nicht an die API selbst. So sollte beispielsweise ein Client keine Informationen aus der URI-Struktur abrufen, da er eng an die tatsächliche API gekoppelt ist.
Ich kenne 2 aktuelle Lösungsarten dazu:
- HAL + JSON verwenden Sie IANA-Link-Beziehungen , um zu beschreiben, was der Link tut, und herstellerspezifische MIME-Typen, um das Schema der Felder zu beschreiben
- von JSON-LD (oder einem anderen RDF-Format) mit Hydra vocab Sie senden RDF-Metadaten entsprechend der Operation, die der Link aufruft. Diese Metadaten können die Validierungsdetails der Felder (xsd vocab) und die Semantik der Felder (Mikrodaten, Mikroformate usw.) enthalten. Diese Informationen sind vollständig von der API-Implementierung abgekoppelt. Dies ist möglicherweise eine bessere Option als die Verwendung herstellerspezifischer MIME-Typen, aber Hydra befindet sich noch in der Entwicklung und HAL ist viel einfacher.
Wie auch immer, Ihre Lösung ist auch gültig, ich denke, Sie sollten beide überprüfen, da sie bereits Standardlösungen sind, und die einheitliche Schnittstelle / selbstbeschreibende Nachrichteneinschränkung von REST fördert die Verwendung vorhandener Standards anstelle von benutzerdefinierten Lösungen. Aber es liegt an Ihnen, ob Sie einen eigenen Standard erstellen möchten.
Ich denke, Sie fragen nach dem Umgang mit Rest-API Metadaten . Im Gegensatz zu SOAP verwendet Rest APIs normalerweise keine Metadaten , aber manchmal kann es ziemlich nützlich sein, sobald Ihre API-Größe größer wird.
Ich denke, Sie sollten sich swagger ansehen. Es ist die eleganteste, die Sie für die Erholung apis finden können. Ich benutze es für einige Zeit und mit der Annotation-Unterstützung ist es ziemlich einfach zu arbeiten. Es hat auch viele Beispiele auf github . Ein weiterer Vorteil ist, dass es schön konfigurierbare ui enthält.
Abgesehen davon können Sie andere Möglichkeiten finden, wie WADL und WSDL 2.0 . Auch wenn ich sie nicht verwende, können Sie hier mehr lesen.
Tags und Links rest post decoupling