Projekt interfejsu API usługi REST do aktualizowania wykresu obiektów

Question

Projektuję interfejs REST API i szukam zalecanej najlepszej praktyki do aktualizowania wykresów obiektów. Moje pytanie jest najlepiej opisane w przykładzie, więc powiedzmy, że mam zasób GET następująco:

URI:/ludzie/123

URI zwraca wykresu obiektu takiego:

{ 
    "name":"Johnny", 
    "country":{"id":100,"name":"Canada"}, 
    "likes":[ 
     {"id":5,"name":"Fruit"}, 
     {"id":100,"name":"Sports"} 
    ] 
} 

Po zezwoleniu klientowi interfejsu API na aktualizację tego zasobu, w jaki sposób można oczekiwać aktualizacji obiektu za pomocą polecenia PUT lub PATCH? Aktualizowanie właściwości "nazwa" jest dość proste, ale nie jestem pewien "kraju" lub "polubień", ponieważ konsument może zmienić tylko związek z innymi obiektami i nie tworzyć nowych.

Oto jeden sposób, aby zwrócić się do aktualizacji:

{ 
    "name":"Bob", 
    "countryId":200 
    "likeIds":[3,10,22] 
} 

Ta aktualizacja zmieni zasób do następujących:

{ 
    "name":"Bob", 
    "country":{"id":200,"name":"United States of America"}, 
    "likes":[ 
     {"id":3,"name":"Cars"}, 
     {"id":10,"name":"Planes"}, 
     {"id":22,"name":"Real Estate"} 
    ] 
} 

Taka konstrukcja wyraźnie i jasno pyta konsumentowi tylko zaktualizować " Identyfikatory "osoby", ale obawiam się, że wykres obiektu dla PUT/PATCH wygląda inaczej niż GET, co sprawia, że ​​interfejs API jest trudny do zapamiętania i zapamiętania. Tak inna opcja jest do żądania PUT/patch następująco:

{ 
    "name":"Bob", 
    "country":{"id":100}, 
    "likes":[ 
     {"id":3}, 
     {"id":10}, 
     {"id":22} 
    ] 
} 

To przyniesie taką samą zmianę w poprzedniej aktualizacji i nie zmienia wykres obiektu. Jednak nie wyjaśnia to konsumentowi API, że można aktualizować tylko "identyfikatory".

W tym scenariuszu, które podejście jest zalecane?

Answer 1

Moim zdaniem powinieneś zachować tę samą strukturę dla żądań GET i PUT. Czemu? Ponieważ dość często mapuje się dane JSON/XML na obiekty i większość (jeśli nie wszystkie) oprogramowania, które faktycznie mapują, najlepiej, jeśli schemat JSON jest zawsze taki sam.

Więc usługa powinna zaakceptować się następujący kod JSON:

{ 
    "name":"Joe", 
    "country":{"id":200,"name":"United States of America"}, 
    "likes":[ 
     {"id":5,"name":"Fruit"} 
    ] 
} 

Jednak to nie musi brać pod uwagę nazwę kraju i może skupić się tylko na id kraju.