Include/embed vs. Link in RESTful-APIs

Question

Das allgemeine Muster für eine RESTful-API besteht also darin, ein einzelnes Objekt mit eingebetteten Verknüpfungen zurückzugeben, die Sie zum Abrufen verwandter Objekte verwenden können. Aber manchmal möchten Sie aus Bequemlichkeit einen ganzen Teil des Objektgraphen auf einmal zurückziehen.

Zum Beispiel: Angenommen, Sie haben einen Speicher-Anwendung mit Kunden, Aufträge und kehrt. Sie möchten die persönlichen Informationen, alle Aufträge anzuzeigen, und alle Erträge, zusammen, für Kunden-ID 12345. (Vermutlich gibt es gute Gründe für die nicht immer Rückkehr Aufträge und kehrt mit Kunden persönliche Informationen.)

Die rein RESTful Weg dies zu tun, ist so etwas wie:

1. GET /
   • eine Liste von Link-Vorlagen gibt, darunter eine für Kunden
abfragen 210
2. GET /customers/12345 (basierend auf Link-Vorlage von /)
   • Daten
   • kehrt Links Kunde gibt diese Kundenaufträge zu erhalten und gibt
3. GET /orders?customerId=12345 (von /customers/12345 Antwort)
   • bekommt die Aufträge für Kunden 12345
4. GET /returns?customerId=12345 (von /customers/12345 Antwort)
   • bekommt die Rendite für die Kunden 12345

Aber es wäre schön, wenn man einmal den customers URI, dies zu ziehen alle in einer Abfrage zurück in der Lage sein, . Gibt es eine Best Practice für diese Art von Convenience-Abfrage, bei der Sie einige oder alle Links umwandeln möchten, anstatt mehrere Anfragen zu stellen? Ich denke, so etwas wie:

GET /customers/12345?include=orders,returns 

aber wenn es eine Möglichkeit, Menschen dies tun da draußen würde ich lieber nicht nur etwas machen.

(FWIW, ich bin nicht einen Laden bauen, also lassen Sie sich nicht über Haarspalterei, ob diese die richtigen Objekte für das Modell, oder wie Sie gehen zu den tatsächlichen Produkten aufschlüsseln, oder was auch immer.)

---

Aktualisiert: Es ist wie diese in HAL speak sieht sind ‚eingebettete Ressourcen‘ genannt, aber in den Beispielen gezeigt wird, scheint es keinen Weg, um zu entscheiden, welche Ressourcen einzubetten.Ich fand one blog post etwas darauf hindeutet, wie das, was ich oben beschrieben, unter Verwendung von embed als Abfrageparameter:

GET /ticket/12?embed=customer.name,assigned_user 

Ist das ein Standard oder halb gängige Praxis, oder einfach nur etwas ein Blogger aus?

Answer 1

Da die Semantik dieser Parameter für jede Link-Beziehung, die sie unterstützt, dokumentiert werden muss, und dass dies mehr oder weniger etwas ist, zu dem man Code schreiben müsste, weiß ich nicht, dass es da ist etwas zu gewinnen, indem man eine übliche Art hat, dies auszudrücken. Die URL-Struktur wird eher von dem bestimmt, was für den Server am einfachsten oder sinnvollsten ist, als von einem bestimmten Standard oder einer Best Practice.

Das heißt, wenn Sie nach Inspiration suchen, können Sie herausfinden, was OData mit der $expand parameter macht und modellieren Sie Ihre Link-Beziehung daraus. Denken Sie daran, dass Sie den Vertrag Ihrer Beziehung immer noch klar definieren sollten, andernfalls könnten Client-Programmierer eine OData-ähnliche Konvention sehen und (fälschlicherweise) davon ausgehen, dass Ihre App vollständig OData-konform ist und sich wie eine verhält.