Jaka jest najlepsza struktura RESTful URL dla zasobu rekurencyjnego?

10

Tworzę usługę RESTfull dla drzewiastej struktury zasobów i zastanawiałem się, jaka byłaby najlepsza struktura adresów URL?

Mam trzy wymagania:

  1. być w stanie uzyskać kolekcję zasobów root
  2. być w stanie uzyskać indywidualny zasób
  3. być w stanie uzyskać zbiór zasobów podrzędnych

Moja obecna myśl to:

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

Myślałem też o przejściu pojedynczych / mnogich ścieżek w celu oznaczenia list lub pojedynczych elementów, ale wiem, że będę miał zasób, który jest taki sam w liczbie mnogiej, jak w liczbie pojedynczej, więc postanowiłem tego nie robić.

Czy ktoś ma jakieś przemyślenia na ten temat? lub masz inny / lepszy sposób na uporządkowanie tego?

web-services Matt Brailsford
źródło
Być może nie rozumiem pytania, ale skoro mówimy o adresach URL, czy SEO jest problemem?
Jon Hopkins
SEO nie jest problemem, nie. Zasadniczo pytam o najlepszą logiczną strukturę URL dla zasobu z odnośnikami.
Matt Brailsford,
Wydaje mi się to całkiem proste.
Tim Post
Jak głęboka może być ta struktura?
Martijn Verburg,
@Martijn głębokość jest nieograniczona
Matt Brailsford,

Odpowiedzi:

11

Co przychodzi mi do głowy: nie pozwól, aby interfejs API RESTful odzwierciedlał rekurencyjność samego adresu URL. Pomyśl o tym, twój zasób to tylko dokumenty.

Jeśli Twoje dokumenty są przechowywane fizycznie zgodnie ze strukturą rekurencyjną, utwórz mapowanie na unikalny identyfikator i użyj identyfikatora w adresie URL:

/rest/documents/{id}

Teraz, jeśli masz takie dokumenty:

| Nazwa dokumentu | DocumentPath | DocumentID |
--------------------------------------------
| abc | / abc | 1 |
| asd | / abc / asd | 2 |
| asd | / asd | 3 |
| boo | / abc / asd / boo | 4 |
| hej | / abc / asd / hey | 5 |

wniosek sprawdzi ten adres URL /abc/asddokumentu

GET /rest/documents/2

Tak więc teraz musisz zapewnić użytkownikom interfejsu API środki do przemierzania swojej struktury przy niewielkim wysiłku. Można to zrobić poprzez zawinięcie ładunku odpowiedzi (dokumentu) w obiekt zawierający dodatkowe informacje o przechodzeniu, takie jak to:

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

pod warunkiem, że oczekujesz, że użytkownicy nie będą tworzyć zbyt wielu dokumentów na jednym poziomie, możesz dołączyć do odpowiedzi listę dzieci. Jeśli tak nie jest, możesz zaoferować użytkownikowi pobranie takich identyfikatorów dokumentów podrzędnych, umożliwiając np. Stronicowanie wyników za pomocą parametrów zapytania:

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

Wreszcie, mówiąc o parametrach zapytania, możesz również podać informacje o ścieżce bezpośrednio przez parametry zapytania:

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

Wszystkie wymienione podejścia oczekują, że zwykły GET /rest/documentszwraca tylko dokumenty root.

netchkin
źródło
1
Dobry pomysł. Jednak związek z dokumentami podrzędnymi nie jest jasny z interfejsu API, jeśli dokumenty podrzędne są uwzględnione w odpowiedzi na dokument. Jeśli dokumenty mają również inne podrzędne źródło, np. Komentarze, zwykle uzyskuje się dostęp do pytań dotyczących dokumentu za pomocą / dokumenty / {id} / pytania. Aby zachować spójność i wyjaśnić związek z dokumentami podrzędnymi w interfejsie API, sugerowałbym, aby dostęp do dokumentów podrzędnych był możliwy przez / dokumenty / {id} / dokumenty-podrzędne. Zwracane reprezentacje to Dokumenty takie jak / dokumenty / {id}. Reszta tego, co tu opisałeś, nadal działa.
Nathan Ward
2

Może coś takiego:

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

gdzie {rootEntity} jest punktem początkowym twojej kolekcji, {leafEntity} to dowolny nazwany węzeł liścia w twoim drzewie.

Możesz dodać kilka parametrów dowolnego z powyższych, aby wybrać, powiedzmy, Najnowsze lub Wszystkie lub coś.

Gary Rowe
źródło