Was ist die beste RESTful-URL-Struktur für eine rekursive Ressource?

10

Ich erstelle einen RESTfull-Service für eine baumartige Ressourcenstruktur und habe mich gefragt, welche URL-Struktur am besten geeignet ist.

Ich habe drei Anforderungen:

  1. in der Lage sein, eine Sammlung von Stammressourcen zu erhalten
  2. in der Lage sein, eine individuelle Ressource zu erhalten
  3. in der Lage sein, eine Sammlung von untergeordneten Ressourcen zu erhalten

Mein aktueller Gedanke ist:

/rest/documents
/rest/documents/{id}
/rest/documents/{id}/documents

Ich habe auch darüber nachgedacht, den Singular / Plural-Weg zu gehen, um Listen oder einzelne Elemente zu bezeichnen, aber ich weiß, dass ich eine Ressource haben werde, die der gleiche Plural wie der Singular ist, also habe ich mich dagegen entschieden.

Hat jemand irgendwelche Gedanken zu den oben genannten? oder haben Sie eine andere / bessere Art, dies zu strukturieren?

web-services Matt Brailsford
quelle
Ich kann die Frage falsch verstehen, aber wenn wir über URLs sprechen, ist SEO ein Problem?
Jon Hopkins
SEO ist kein Problem, nein. Ich frage grundsätzlich nach der besten logischen URL-Struktur für eine selbstreferenzierende Ressource.
Matt Brailsford
Das scheint mir ziemlich einfach zu sein.
Tim Post
Wie tief kann diese Struktur gehen?
Martijn Verburg
@ Martinijn die Tiefe ist uneingeschränkt
Matt Brailsford

Antworten:

11

Was mir in den Sinn kommt, ist: Lassen Sie Ihre RESTful-API nicht die Rekursivität in der URL selbst widerspiegeln. Denken Sie mal darüber nach, Ihre Ressource sind nur die Dokumente.

Wenn Sie Ihre Dokumente gemäß der rekursiven Struktur physisch gespeichert haben, erstellen Sie eine Zuordnung zu einer eindeutigen ID und verwenden Sie die ID in der URL:

/rest/documents/{id}

Wenn Sie Ihre Dokumente wie folgt haben:

| Dokumentname | DocumentPath | DocumentID |
----------------------------------------
| abc | / abc | 1 |
| asd | / abc / asd | 2 |
| asd | / asd | 3 |
| boo | / abc / asd / boo | 4 |
| hey | / abc / asd / hey | 5 |

Die Anfrage würde diese URL für ein /abc/asdDokument konsultieren

GET /rest/documents/2

Jetzt müssen Sie den Benutzern Ihrer API die Möglichkeit geben, Ihre Struktur mit geringem Aufwand zu durchlaufen. Dies kann erreicht werden, indem Sie Ihre Antwortnutzlast (Dokument) in ein Objekt einwickeln, das zusätzliche Durchquerungsinformationen enthält, wie folgt:

{
   data: { /* your document goes here */ },
   parent: {"abc": 1 },
   children: [ { "boo": 4 }, { "hey": 5} ]
}

Vorausgesetzt, Sie erwarten, dass Benutzer nicht zu viele Dokumente auf einer Ebene erstellen, können Sie eine Liste der untergeordneten Elemente in die Antwort aufnehmen. Wenn dies nicht der Fall ist, können Sie dem Benutzer anbieten, untergeordnete Dokument-IDs wie diese abzurufen, um beispielsweise die Ergebnisse über Querystring-Parameter zu pagen:

GET /rest/documents/2/children?page=2&size=50

Wenn Sie von Querystring-Parametern sprechen, können Sie die Pfadinformationen auch direkt über die Querystring-Parameter bereitstellen:

GET /rest/documents?path=somepath&page=1&size=42

Alle genannten Ansätze erwarten, dass die Ebene GET /rest/documentsnur Stammdokumente zurückgibt.

Netchkin
quelle
1
Gute Idee. Die Beziehung zu den untergeordneten Dokumenten ist jedoch aus der API nicht ersichtlich, wenn die untergeordneten Dokumente in der Antwort für ein Dokument enthalten sind. Wenn Dokumente auch eine andere Unterressource haben, z. B. Kommentare, greifen Sie normalerweise mit / documents / {id} / question auf die Fragen für ein Dokument zu. Um konsistent zu sein und die Beziehung zu untergeordneten Dokumenten in der API klar zu machen, würde ich vorschlagen, dass auf untergeordnete Dokumente über / documents / {id} / child-documents zugegriffen wird. Die zurückgegebenen Darstellungen wären Dokumente wie / documents / {id}. Der Rest von dem, was Sie hier beschrieben haben, funktioniert also auch noch.
Nathan Ward
2

So etwas vielleicht:

/rest/{rootEntity}/Item/{leafEntity}/{id}
/rest/{entity}/ItemList
/rest/{entity}/ItemList/{leafEntity}

Dabei ist {rootEntity} der Ausgangspunkt Ihrer Sammlung, {leafEntity} ein beliebiger benannter Blattknoten in Ihrem Baum.

Sie können einige der oben genannten Parameter anhängen, um beispielsweise Neueste oder Alle oder etwas auszuwählen.

Gary Rowe
quelle