"Best Practice" für eine erholsame POST-Reaktion

217

Also nichts Neues hier Ich versuche nur eine Klarstellung zu bekommen und kann anscheinend keine in anderen Posts finden.

Ich erstelle unruhig eine neue Ressource, sagen wir:

/books (POST)

mit einem Körper:

{
  title: 'The Lion, the Witch and the Wardrobe',
  author: 'C. S. Lewis'
}

Ich weiß, dass ich eine 201 (Erstellt) mit einem Standortheader der neuen Ressource zurückgeben sollte:

Location: /books/12345

Die Frage, die ich anscheinend nicht für mich selbst beantworten kann, ist, was der Server im Körper zurückgeben soll.

Ich habe oft diese Art von Antwort gemacht:

{
  id: 12345,
  title: 'The Lion, the Witch and the Wardrobe',
  author: 'C. S. Lewis'
}

Ich habe dies aus mehreren Gründen getan:

Ich habe API für Front-End-Frameworks wie AngularJs geschrieben. In meinem speziellen Fall verwende ich eckige Ressourcen und benötige häufig nur die ID der Ressource, um sie zu finden. Wenn ich die ID im Antworttext nicht zurückgeben würde, müsste ich sie aus dem Location-Header analysieren.
In einem GET aller Bücher gebe ich normalerweise das gesamte Objekt zurück, nicht nur die ID. In diesem Sinne muss mein Client-Code nicht unterscheiden, woher die ID stammt (Standort-Header oder Body).

Jetzt weiß ich, dass ich hier wirklich in der Grauzone bin, aber die meisten Leute sagen, dass die Rückgabe der gesamten Ressource eine „schlechte“ Praxis ist. Was aber, wenn der Server der Ressource Informationen ändert / hinzufügt? Es fügt definitiv die ID hinzu, kann aber auch andere Dinge wie einen Zeitstempel hinzufügen. Für den Fall, dass ich nicht die gesamte Ressource zurückgebe, ist es wirklich besser, einen POST durchzuführen, die ID zurückzugeben und dann den Client ein GET ausführen zu lassen, um die neue Ressource abzurufen.

rest angularjs angularjs-resource

— verlorene Übersetzung
quelle

Ich persönlich bevorzuge leere Körper für POST-Antworten. Sollte der RESTful Location-Headerwert nicht ein URI (eindeutige Ressourcen-ID) sein? Vielleicht sollten Sie es als ID verwenden und nicht analysieren, um eine serverinterne ID herauszufinden. IMO, RESTful API-Konsumenten sollten mithilfe der bereitgestellten Hyperlinks navigieren und keinen Pfad erstellen, um zu erraten, wo ein bestimmter Server Ressourcen findet ... Und kennt der Client den Status der gerade erstellten Ressource nicht bereits? Wenn Sie dies wiederholen, werden die Netzwerkressourcen verschwendet.

— ch4mp

Für Erstellen / Einfügen, Status 201 - ERSTELLT, Header-Speicherort → localhost: 8080 / employee / 1 (siehe: hier )

— Hassan Tareq

Antworten:

129

Das Zurückgeben des gesamten Objekts bei einem Update scheint nicht sehr relevant zu sein, aber ich kann kaum erkennen, warum das Zurückgeben des gesamten Objekts beim Erstellen in einem normalen Anwendungsfall eine schlechte Praxis wäre. Dies wäre zumindest nützlich, um die ID leicht zu erhalten und gegebenenfalls die Zeitstempel zu erhalten. Dies ist eigentlich das Standardverhalten beim Gerüstbau mit Rails.

Ich sehe wirklich keinen Vorteil darin, nur die ID zurückzugeben und danach eine GET-Anfrage zu stellen, um die Daten zu erhalten, die Sie mit Ihrem ersten POST hätten erhalten können.

Wie auch immer, solange Ihre API konsistent ist, sollten Sie das Muster auswählen, das Ihren Anforderungen am besten entspricht. Es gibt keine korrekte Methode zum Erstellen einer REST-API, imo.

— Daniel Perez
quelle

Ich weiß, dass dies alt ist, aber ich kann ein überzeugendes Argument für die Verwendung eines GET nach Ihrem POST liefern. In der http / 1.1-Spezifikation kann jedes historische Tool die Cache-Einstellungen ignorieren, die von Ihrer GET-Antwort zurückgegeben wurden. Wenn Ihr Benutzer also die Schaltfläche "Zurück" im Browser verwendet, um zu dieser Seite zurückzukehren, nachdem Sie sie mit dem POST aktualisiert haben, kann sie veraltet sein zwischengespeicherte Daten aus dem ursprünglichen GET. Wenn Sie also das GET wiederverwenden, können Sie den Cache aktualisieren und einen besseren Überblick darüber erhalten, wie die Seite beim Verlassen aussah ...

— Shaded

@Shaded Wenn die API auch von Apps verwendet werden soll, gilt Ihr Argument für zwei Anforderungen nicht. Dort werden die Daten normalerweise zwischengespeichert, indem Objekte eines Modelltyps gespeichert werden. Dies erfolgt normalerweise mit der Antwort auf POST-Anforderungen. Und in Bezug auf Browser tut die Antwort auf eine POST-Anfrage nicht wirklich weh, solange noch ein GET-API-Endpunkt vorhanden ist.

— Jeehut

Ich abonniere, was Daniel hier sagt. Selbst wenn Sie ausgereifte Frameworks wie Spring Data überprüfen, geben sie immer das gesamte Objekt zurück, nachdem sie es beibehalten haben. Ich denke, es ist eine gute Praxis, da Sie

— Frandevel

205

Die Rückgabe des neuen Objekts entspricht dem REST-Prinzip "Uniform Interface - Manipulation von Ressourcen durch Repräsentationen". Das vollständige Objekt ist die Darstellung des neuen Status des erstellten Objekts.

Hier finden Sie eine wirklich hervorragende Referenz für das API-Design: Best Practices für das Entwerfen einer pragmatischen RESTful-API

Hier finden Sie eine Antwort auf Ihre Frage: Updates & Erstellung sollten eine Ressourcendarstellung zurückgeben

Es sagt:

Um zu verhindern, dass ein API-Konsument die API für eine aktualisierte Darstellung erneut aufrufen muss, muss die API die aktualisierte (oder erstellte) Darstellung als Teil der Antwort zurückgeben.

Scheint mir sehr pragmatisch und passt zu dem oben erwähnten REST-Prinzip.

— grahamesd
quelle

Wie wäre es mit der Rückgabe des gesamten Satzes relevanter Objekte? Auf diese Weise kann eine mögliche Sortierung serverseitig erfolgen und die Front-End-Implementierung

— vereinfachen

Diese Best Practices sind jedoch nicht die besten. Der Autor besagt, dass HATEOAS, das genauso wichtig ist wie andere Prinzipien, nicht verwendet werden darf, weil "es nicht bereit ist". HATEOAS wird niemals "bereit" sein, da alle RESTful-Prinzipien nur architektonische Gestaltungsprinzipien sind, keine spezifische Implementierung. Die zitierte Referenz handelt von der Vision des Autors bezüglich der RESTful-API, die aufgrund des Löschens von HATEOAS überhaupt nicht RESTful ist. Deshalb ist dies nicht die beste Referenz :)

— Marcinn

@marcinn - Sie werden feststellen, dass die ursprüngliche Frage Zitate um 'Best' enthielt, denke ich, weil es in diesem Bereich viele Meinungen gibt. Die Referenz, auf die ich hingewiesen habe, hat sich als praktisch erwiesen. Wenn Sie eine bessere Referenz haben, teilen Sie diese bitte mit. Ich bin immer offen für mehr zu lernen.

— Grahamesd

@grahamesd Eine Implementierung ist etwas anderes als das Prinzip / Muster des Architekturdesigns. Niemand kann erwarten, dass HATEOAS eines Tages fertig sein wird, aber es besteht die Möglichkeit, dass jemand eine von vielen akzeptable Implementierung erstellt. Vinay schrieb auch über die Zuordnung von http-Methoden zu URLs und bestimmten Operationen (CRUD), erklärte, dass die Versionierung durch das Präfixieren von URLs pragmatischer sei, und schrieb, dass das Filtern nach Abfrageparametern ein guter Weg sei ... es ist in Ordnung, aber all dies hat wenig zu tun mit RESTful Architektur tun. Er schrieb über eine Art Vertrag. Das ist in Ordnung für die HTTP-API, aber nennen Sie es nicht RESTful.

— Marcinn

@grahamesd Hier sind einige Beiträge, die dies erklären: - medium.com/@andrea.chiarelli/… - restfulapi.net

— marcinn