Progettazione API REST per l'aggiornamento del grafico ad oggetti

Question

Sto progettando un'API REST e sto cercando la best practice consigliata per l'aggiornamento dei grafici degli oggetti. La mia domanda è meglio spiegato in un esempio, quindi diciamo che ho una risorsa GET come segue:

URI:/persone/123

Questo URI restituisce un oggetto grafico come questo:

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

Quando consenti al cliente dell'API di aggiornare questa risorsa, come ti aspetti che l'oggetto venga aggiornato tramite PUT o PATCH? Aggiornare la proprietà "name" è piuttosto semplice, ma non sono sicuro di "country" o "likes", in quanto il consumatore può solo modificare la relazione con altri oggetti e non crearne di nuovi.

Ecco un modo per richiedere l'aggiornamento:

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

Questo aggiornamento cambierà la risorsa al seguente:

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

Questo design esplicitamente e chiaramente chiede al consumatore di aggiornare solo il " ID "della" Persona ", ma sono preoccupato che il grafico dell'oggetto per un PUT/PATCH appaia diverso dal GET, rendendo l'API difficile da imparare e ricordare. Così un'altra opzione è quella di richiedere PUT/PATCH come segue:

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

Ciò comporterà lo stesso cambiamento come l'aggiornamento precedente e non alterare l'oggetto grafico. Tuttavia, non chiarisce al consumatore dell'API che solo gli "ID" possono essere aggiornati.

In questo scenario, quale approccio è raccomandato?

Answer 1

Secondo me dovresti stare con la stessa struttura per entrambe le richieste GET e PUT. Perché? Perché è abbastanza comune mappare i dati JSON/XML in oggetti e la maggior parte (se non tutti) i software che fanno la mappatura effettiva funzionano meglio se lo schema JSON è sempre lo stesso.

Così il vostro webservice dovrebbe accettare un seguente codice JSON:

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

Tuttavia non deve prendere in considerazione il nome del paese e può concentrarsi solo sul id paese.