Jakie są najlepsze praktyki dotyczące zagnieżdżonych zasobów REST?

O ile mogę stwierdzić, każdy pojedynczy zasób powinien mieć tylko jedną ścieżkę kanoniczną . Więc w poniższym przykładzie, jakie byłyby dobre wzorce adresów URL?

Weźmy na przykład reprezentację firm. W tym hipotetycznym przykładzie każda firma posiada 0 lub więcej działów, a każdy dział posiada 0 lub więcej pracowników.

Dział nie może istnieć bez powiązanej firmy.

Pracownik nie może istnieć bez powiązanego działu.

Teraz znajdę naturalną reprezentację wzorców zasobów.

• /companies Zbiór firm - Akceptuje dla nowej firmy. Zdobądź całą kolekcję.
• /companies/{companyId}Indywidualna firma. Akceptuje GET, PUT i DELETE
• /companies/{companyId}/departmentsAkceptuje POST dla nowego przedmiotu. (Tworzy dział w firmie).
• /companies/{companyId}/departments/{departmentId}/
• /companies/{companyId}/departments/{departmentId}/employees
• /companies/{companyId}/departments/{departmentId}/employees/{empId}

Biorąc pod uwagę ograniczenia, w każdej sekcji uważam, że ma to sens, jeśli jest nieco zagnieżdżone.

Jednak moja trudność pojawia się, gdy chcę wymienić ( GET) wszystkich pracowników we wszystkich firmach.

Wzorzec zasobów dla tego byłby najbardziej zbliżony do /employees(Zbiór wszystkich pracowników)

Czy to oznacza, że ​​powinienem /employees/{empId}również mieć, ponieważ jeśli tak, to istnieją dwa identyfikatory URI, aby uzyskać ten sam zasób?

A może cały schemat powinien zostać spłaszczony, ale oznaczałoby to, że pracownicy są zagnieżdżonymi obiektami najwyższego poziomu.

Na poziomie podstawowym /employees/?company={companyId}&department={deptId}zwraca dokładnie ten sam widok pracowników, co najgłębiej zagnieżdżony wzór.

Jaka jest najlepsza praktyka w zakresie wzorców adresów URL, w których zasoby są własnością innych zasobów, ale powinny być dostępne osobne zapytania?

To, co zrobiłeś, jest poprawne. Zasadniczo do tego samego zasobu może być wiele identyfikatorów URI - nie ma reguł, które mówią, że nie powinieneś tego robić.

Ogólnie rzecz biorąc, być może będziesz musiał uzyskać dostęp do elementów bezpośrednio lub jako podzbiór czegoś innego - więc twoja struktura ma dla mnie sens.

Tylko dlatego, że pracownicy są dostępni w dziale:

company/{companyid}/department/{departmentid}/employees

Nie oznacza to, że nie mogą być również dostępne w firmie:

company/{companyid}/employees

Co zwróci pracowników dla tej firmy. Zależy to od tego, czego potrzebuje Twój konsumujący klient - do tego właśnie powinieneś projektować.

Mam jednak nadzieję, że wszystkie procedury obsługi adresów URL używają tego samego kodu zabezpieczającego do zaspokojenia żądań, aby nie powielać kodu.

Wypróbowałem obie strategie projektowania - zagnieżdżone i nie zagnieżdżone punkty końcowe. Znalazłem to:

1. jeśli zagnieżdżony zasób ma klucz podstawowy, a nie masz jego nadrzędnego klucza podstawowego, struktura zagnieżdżona wymaga jego uzyskania, nawet jeśli system go nie wymaga.

2. zagnieżdżone punkty końcowe zwykle wymagają redundantnych punktów końcowych. Innymi słowy, będziesz potrzebować dodatkowego punktu końcowego / pracowników, aby uzyskać listę pracowników z różnych działów. Jeśli masz / pracowników, co dokładnie kupują / firmy / działy / pracownicy?

3. zagnieżdżanie punktów końcowych nie rozwija się tak ładnie. Np. Być może nie będziesz musiał szukać pracowników teraz, ale możesz później, a jeśli masz zagnieżdżoną strukturę, nie masz innego wyboru, jak dodać kolejny punkt końcowy. W przypadku projektu zagnieżdżonego wystarczy dodać więcej parametrów, co jest prostsze.

4. czasami zasób może mieć wiele rodzajów rodziców. W rezultacie powstaje wiele punktów końcowych, wszystkie zwracają ten sam zasób.

5. redundantne punkty końcowe utrudniają pisanie dokumentów, a także utrudniają naukę interfejsu API.

Krótko mówiąc, wydaje się, że nie zagnieżdżony projekt pozwala na bardziej elastyczny i prostszy schemat punktu końcowego.

Przesunąłem to, co zrobiłem, z pytania do odpowiedzi, w której prawdopodobnie więcej osób je zobaczy.

To, co zrobiłem, to mieć punkty końcowe tworzenia w zagnieżdżonym punkcie końcowym. Kanoniczny punkt końcowy do modyfikowania lub odpytywania elementu nie znajduje się w zagnieżdżonym zasobie .

Tak więc w tym przykładzie (wystarczy wymienić punkty końcowe, które zmieniają zasób)

• POST /companies/ tworzy nową firmę zwraca link do utworzonej firmy.
• POST /companies/{companyId}/departments po umieszczeniu działu tworzy nowy dział zwraca link do /departments/{departmentId}
• PUT /departments/{departmentId} modyfikuje dział
• POST /departments/{deparmentId}/employees tworzy nowy pracownik zwraca link do /employees/{employeeId}

Istnieją więc zasoby na poziomie głównym dla każdej kolekcji. Jednak tworzenie odbywa się w obiekcie będącym właścicielem .

Przeczytałem wszystkie powyższe odpowiedzi, ale wygląda na to, że nie mają wspólnej strategii. Znalazłem dobry artykuł na temat najlepszych praktyk w API Design z Microsoft Documents . Myślę, że powinieneś polecić.

W bardziej złożonych systemach kuszące może być dostarczanie identyfikatorów URI, które umożliwiają klientowi nawigację na kilku poziomach relacji, takich jak: /customers/1/orders/99/products.Jednak ten poziom złożoności może być trudny do utrzymania i nieelastyczny, jeśli relacje między zasobami zmienią się w przyszłości. Zamiast tego staraj się, aby identyfikatory URI były stosunkowo proste . Gdy aplikacja ma odwołanie do zasobu, powinno być możliwe użycie tego odwołania do znalezienia elementów związanych z tym zasobem. Poprzednie zapytanie można zastąpić identyfikatorem URI, /customers/1/ordersaby znaleźć wszystkie zamówienia dla klienta 1, a następnie /orders/99/productsznaleźć produkty w tym zamówieniu.

.

Wskazówka

Unikaj wymagania, aby identyfikatory URI zasobów były bardziej złożone niż collection/item/collection.

Wygląd adresów URL nie ma nic wspólnego z usługą REST. Wszystko idzie. W rzeczywistości jest to „szczegół implementacji”. Więc tak jak nazywasz swoje zmienne. Muszą być jedyne w swoim rodzaju i trwałe.

Nie marnuj na to zbyt wiele czasu, po prostu dokonaj wyboru i trzymaj się go / bądź konsekwentny. Na przykład, jeśli korzystasz z hierarchii, robisz to dla wszystkich swoich zasobów. Jeśli korzystasz z parametrów zapytań ... itd., Podobnie jak konwencje nazewnictwa w kodzie.

Dlaczego tak ? O ile mi wiadomo, API „RESTful” ma być możliwe do przeglądania (wiesz… „Hypermedia jako silnik stanu aplikacji”), dlatego klient API nie dba o to, jakie są twoje adresy URL, o ile są ważne (nie ma SEO, żaden człowiek nie musiałby czytać tych „przyjaznych adresów URL”, z wyjątkiem tego, że może służyć do debugowania ...)

To, jak ładny / zrozumiały jest adres URL w interfejsie API REST, jest interesujące tylko dla programisty interfejsu API, a nie dla klienta interfejsu API, tak jak nazwa zmiennej w kodzie.

Najważniejsze jest to, że klient interfejsu API wie, jak interpretować typ multimediów. Na przykład wie, że:

• Twój typ multimediów ma właściwość links, która zawiera listę dostępnych / powiązanych linków.
• Każdy link jest identyfikowany przez relację (tak jak przeglądarki wiedzą, że link [rel = "arkusz stylów"] oznacza, że ​​jego arkusz stylów lub rel = favico jest linkiem do favicon ...)
• i wie, co oznaczają te relacje („firmy” oznaczają listę firm, „wyszukiwanie” oznacza szablonowy adres URL do wyszukiwania na liście zasobów, „działy” oznaczają działy bieżącego zasobu)

Poniżej znajduje się przykładowa wymiana HTTP (ciała są w yaml, ponieważ łatwiej jest pisać):

Żądanie

GET / HTTP/1.1
Host: api.acme.io
Accept: text/yaml, text/acme-mediatype+yaml

Odpowiedź: lista linków do głównego zasobu (firmy, ludzie, cokolwiek ...)

HTTP/1.1 200 OK
Date: Tue, 05 Apr 2016 15:04:00 GMT
Last-Modified: Tue, 05 Apr 2016 00:00:00 GMT
Content-Type: text/acme-mediatype+yaml

# body: this is your API's entrypoint (like a homepage)  
links:
  # could be some random path https://api.acme.local/modskmklmkdsml
  # the only thing the API client cares about is the key (or rel) "companies"
  companies: https://api.acme.local/companies
  people: https://api.acme.local/people

Żądanie: link do firm (przy użyciu body.links.companies poprzedniej odpowiedzi)

GET /companies HTTP/1.1
Host: api.acme.local
Accept: text/yaml, text/acme-mediatype+yaml

Odpowiedź: częściowa lista firm (poniżej pozycji), zasób zawiera powiązane linki, takie jak link do uzyskania następnych kilku firm (body.links.next) inny (szablonowy) link do wyszukiwania (body.links.search)

HTTP/1.1 200 OK
Date: Tue, 05 Apr 2016 15:06:00 GMT
Last-Modified: Tue, 05 Apr 2016 00:00:00 GMT
Content-Type: text/acme-mediatype+yaml

# body: representation of a list of companies
links:
  # link to the next page
  next: https://api.acme.local/companies?page=2
  # templated link for search
  search: https://api.acme.local/companies?query={query} 
# you could provide available actions related to this resource
actions:
  add:
    href: https://api.acme.local/companies
    method: POST
items:
  - name: company1
    links:
      self: https://api.acme.local/companies/8er13eo
      # and here is the link to departments
      # again the client only cares about the key department
      department: https://api.acme.local/companies/8er13eo/departments
  - name: company2
    links:
      self: https://api.acme.local/companies/9r13d4l
      # or could be in some other location ! 
      department: https://api2.acme.local/departments?company=8er13eo

Tak więc, jak widzisz, jeśli korzystasz z linków / relacji, sposób, w jaki tworzysz ścieżkę, część twoich adresów URL nie ma żadnej wartości dla twojego klienta API. A jeśli komunikujesz strukturę swoich adresów URL swojemu klientowi jako dokumentację, to nie robisz REST (lub przynajmniej nie Poziom 3 zgodnie z „ modelem dojrzałości Richardsona ”)

Nie zgadzam się z tego rodzaju ścieżką

GET /companies/{companyId}/departments

Jeśli chcesz dostać działy, myślę, że lepiej jest użyć zasobu / departments

GET /departments?companyId=123

Przypuszczam, że masz companiestabelę i departmentstabelę, a następnie klasy, aby zmapować je w używanym języku programowania. Zakładam również, że działy mogą być przyłączone do innych podmiotów niż firmy, więc zasób / działy jest prosty, wygodnie jest mieć zasoby odwzorowane na tabele, a także nie potrzebujesz tylu punktów końcowych, ponieważ możesz ponownie użyć

GET /departments?companyId=123

na przykład do dowolnego wyszukiwania

GET /departments?name=xxx
GET /departments?companyId=123&name=xxx
etc.

Jeśli chcesz utworzyć dział,

POST /departments

należy użyć zasobu, a treść żądania powinna zawierać identyfikator firmy (jeśli dział można powiązać tylko z jedną firmą).

Rails zapewnia rozwiązanie tego problemu: płytkie zagnieżdżanie .

Myślę, że jest to dobre, ponieważ w przypadku bezpośredniego kontaktu ze znanym zasobem nie ma potrzeby korzystania z zagnieżdżonych tras, co omówiono w innych odpowiedziach tutaj.