Sammlungen, Artikel, Verben und REST-Interface-Design: Was sollten POSTs zurückgeben?

Question

Ich entwerfe eine REST-Schnittstelle und bin verwirrt darüber, was das Verb einfügen/aktualisieren/löschen zurückgeben soll (als Inhalt der Antwort). Betrachten wir ein inteface für Invoice Entitäten zugänglich api/invoices:

• GET /api/invoices gibt eine Liste von Rechnungen
• GET /api/invoices/123 kehrt die Rechnung mit der ID 123
• POST /api/invoices fügt eine neue Rechnung (ID generiert am Server)
• POST /api/invoices/123 aktualisiert Rechnung mit ID 123
• DELETE /api/invoices/123 löscht Rechnung mit ID 123

Es ist ziemlich offensichtlich, was die ersten beiden Methode zurückgeben sollte, aber wie wäre es mit den Einfüge-/Update/Delet? Eine naheliegende Antwort ist, dass add das neu erstellte Element zurückgeben sollte (dh genau die gleiche Antwort wie GET/api/rechnungen/id), update sollte das aktualisierte Element zurückgeben (wieder dasselbe wie ein GET) und delete sollte wahrscheinlich nichts zurückgeben (leerer Inhalt). Dies alles macht Sinn und ist konsistent.

Aber meine Probleme beginnen, wenn Sie Dinge betrachten, die nicht so einfach wie eine Rechnungseinheit sind. Betrachten wir zum Beispiel eine add Anfrage, die nicht nur das Element hinzufügt, sondern tatsächlich einige zusätzliche Informationen über die Hinzufügeoperation zurückgeben muss: das Objekt wurde akzeptiert (Erfolg), das Objekt ist ein Duplikat (Erfolg mit Info), das Objekt wurde ignoriert (Erfolg mit Info, ich werde nicht ins Detail gehen, warum), der Gegenstand wurde abgelehnt (Misserfolg). Auch in meinem Fall gibt es zusätzliche Informationen, die ich zurückgeben möchte, wie zum Beispiel eine 'Antwort' Info, die für den Bucket in die neu hinzugefügten Items voreingestellt ist. Ich überlegte, alle zusätzlichen Informationen in die HTTP-Header als eine Art von Out-of-Band-Informationen (wie zusätzliche Statuscodes im Bereich 200 und sogar benutzerdefinierte Header) zu setzen, ist aber ein Hack, und der "Antwort" -Teil kann tatsächlich größer sein als der Gegenstand selbst. So denke ich jetzt das add Verb, um einen völlig neuen Typ zurückzugeben, ein Element, das die Add-Info enthält (Status, Antwort, ID des neuen Artikels, enthält den gesamten neuen Artikel). Es wird sicherlich die Arbeit erledigt, aber ich vermisse die schöne Symmetrie, die ich zuvor hatte.

Wäre das eine gute Übung (wenn man einen Artikel vom Typ 'foo' hinzufügt, ist die Retoure vom Typ 'bar') oder werde ich in 6 Monaten zurückschauen und meine Haare ziehen, weil ich die Katze raus lasse von der Tasche? Wenn ich bei 'any access on foo' zurückbleibe foo, einschließlich add ', dann müsste der Client einen zusätzlichen Aufruf nach der' add 'Operation machen, um die Information zu erhalten, an der er wirklich interessiert ist (dh die' Antwort ').

Answer 1

Ihre Antwort sollte ziemlich komplex sein. Es sollte nicht mit der eingehenden Anfrage übereinstimmen. Wir verwenden JSON und wir haben einige zusätzliche Informationen zusätzlich zu dem Objekt.

Typische Reponse:

[{ "ID": the generated ID, "TYPE": the actual class name, "OBJECT": { the object } }] 

POST sollte das Objekt zurückgeben, die erstellt wurde. Wenn Sie zusätzliche Informationen haben (was keine gute Idee ist), können Sie das in der Antwortnachricht tragen.

PUT sollte das Ergebnis der Aktualisierung zurückgeben.

DELETE, wie GET, kann nur einen Status zurückgeben.

Zusätzliche Informationen im Status ist kein Hack - deshalb sind die Statuscodes so offen.

• der Artikel angenommen wurde (Erfolg) - Status 200 OK

• das Element ist ein Duplikat (Erfolg mit info) - Ich bin nicht sicher, was möglich, Informationen Sie darüber hinaus das hätten endgültiges Objekt erstellt, aber dies ist ein Platz für 20x - OK MIT INFO-Status.

• der Artikel wurde ignoriert (Erfolg mit Info, ich werde nicht ins Detail warum) - das ist mehrdeutig. Ich würde es nicht Erfolg nennen, ich würde es ein 40x - IGNORED nennen. Sie können es ein 20X - IGNORED nennen, wenn Sie nicht in die Details warum gehen können.

• der Artikel wurde abgelehnt (Fehler). Dies ist eine einfache alte 40X REJECTED Nachricht.

Answer 2

Eine Option für die POST kehrt zu prüfen, ist es die zusätzliche Informationen und einen Link auf das neu erstellte Objekt zu haben, zurückzukehren. Dies führt zu einer netten Mittellinie zwischen der Rückgabe derselben Sache, die GET zurückgeben würde, und der Rückgabe einer völlig unterschiedlichen Entität.