REST API - zawierają powiązane szczegóły obiektu lub tylko ID

Question

Jaka jest lepsza praktyka projektowa?

Jeśli mam obiekt A i zawiera on pewne powiązane obiekty, na przykład mam obiekt samochodu i jego różne typy.

Mam na żądanie api.example.org/cars/1 reagują tylko z identyfikatorem do tych zasobów (więc jeśli ktoś potrzebne dane o nich innym wywołanie API jest wymagany przy api.example.org/type/1)

{ 
    "id": 1, 
    "name": "Some Car", 
    "types": [ 
     1, 
     2 
    ] 
} 

lub podać szczegóły na temat tych środków, a także

{ 
    "id": 1, 
    "name": "Some Car", 
    "types": [ 
     { 
      "id": 1, 
      "name": "Some Type", 
      "something": "Blah" 
     }, 
     { 
      "id": 2, 
      "name": "Some Type", 
      "something": "Blah" 
     } 
    ] 
} 

Lub podaj opcjonalny parametr, taki jak "displayAll", a następnie tablicę z nazwami parametrów, które powinny zostać pobrane w jednym wywołaniu API (w tym przypadku typy).

Answer 1

To dotyka jednej z podstawowych zasad REST o nazwie HATEOAS (Hypermedia jako silnik stanu aplikacji).

Identyfikatory obiektów są bezużyteczne i pozbawione znaczenia dla klientów. Co z nimi robisz? Nakarmić je funkcją wyszukiwania? Zbuduj nowy URI z dołączonymi do niego końcami? Zadzwoń pod numer 1-800 i zapytaj, co z nimi zrobić? Wydrukuj je na papierze i wyślij do agencji rządowej, która pomoże klientom API znaleźć kolejne kroki?

Wystarczy zwrócić cały URI, przez cały czas. Identyfikator podany klientowi powinien zawsze być identyfikatorem URI - jest to coś, co jednoznacznie identyfikuje dany zasób i może być użyte do jego pobrania, aktualizacji lub usunięcia.

Answer 2

Wolę bez parametrów wersję 1, ale chciałbym faworyzować coś, gdzie lokalizacja zasobu typu jest zwracana, tak aby klient mógł wybrać, czy pobrać te zasoby.

W przeciwnym razie nie poruszamy się po dokumentach. Raczej będziemy polegać na danych pozapasmowych, takich jak wcześniejsze poznanie ścieżki do typu.