REST-API-Design für die Aktualisierung des Objektdiagramms

Question

Ich entwerfe eine REST-API und suche nach der empfohlenen bewährten Methode zur Aktualisierung von Objektdiagrammen. Meine Frage ist in einem Beispiel am besten erklärt, also lassen Sie uns sagen, dass ich eine GET-Ressource wie folgt:

URI:/people/123

Diese URI ein Objekt Diagramm wie folgt zurückgibt:

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

Wie können Sie erwarten, dass das Objekt über PUT oder PATCH aktualisiert wird, wenn der API-Consumer diese Ressource aktualisieren kann? Das Aktualisieren der "name" -Eigenschaft ist ziemlich einfach, aber ich bin mir nicht sicher über "Land" oder "Likes", da der Verbraucher nur die Beziehung zu anderen Objekten ändern und keine neuen erstellen kann. Hier

ist ein Weg, um das Update zu erhalten:

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

Dieses Update wird die Ressource wie folgt zu ändern:

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

Dieser Entwurf ausdrücklich und klar fordert den Verbraucher nur zu aktualisieren, die " IDs "der" Person ", aber ich bin besorgt, dass das Objektdiagramm für ein PUT/PATCH anders aussieht als das GET, wodurch das API schwer zu erlernen und zu merken ist. Also eine weitere Option ist die PUT/PATCH zu beantragen, wie folgt:

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

Dies wird die gleiche Änderung wie das vorherige Update liefern und nicht das Objektgraph nicht verändert. Es macht dem API-Consumer jedoch nicht klar, dass nur die "IDs" aktualisiert werden können.

In diesem Szenario, welcher Ansatz wird empfohlen?

Answer 1

Meiner Meinung nach sollten Sie mit der gleichen Struktur für beide bleiben, GET und PUT Anfragen. Warum? Weil es sehr gebräuchlich ist, JSON/XML-Daten in Objekten abzubilden, und die meisten (wenn nicht alle) Software, die das eigentliche Mapping durchführt, funktioniert am besten, wenn das JSON-Schema immer gleich ist.

Also Ihr Webservice sollte akzeptieren einen folgenden JSON-Code:

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

jedoch nicht den Namen des Landes zu berücksichtigen hat und kann Fokus nur auf dem Land ID.