REST Diseño de API para actualizar el gráfico de objetos

Question

Estoy diseñando una API REST y estoy buscando la mejor práctica recomendada para actualizar gráficos de objetos. Mi pregunta se explica mejor con un ejemplo, así que vamos a decir que tengo un recurso GET de la siguiente manera:

URI:/personas/123

Este URI devuelve un objeto gráfico de esta manera:

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

Al permitir que el consumidor API actualice este recurso, ¿cómo esperaría que el objeto se actualice mediante PUT o PATCH? La actualización de la propiedad "nombre" es bastante sencilla, pero no estoy seguro acerca de "país" o "me gusta", ya que el consumidor solo puede cambiar la relación con otros objetos y no crear otros nuevos.

Aquí es una manera de solicitar la actualización:

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

Esta actualización cambiará el recurso a lo siguiente:

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

Este diseño hace explícita y claramente al consumidor para actualizar sólo el " Identifica "la" Persona ", pero me preocupa que el gráfico de objetos para un PUT/PATCH sea diferente al GET, lo que hace que la API sea difícil de aprender y recordar. Así pues, otra opción es solicitar el PUT/PATCH de la siguiente manera:

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

Esto producirá el mismo cambio que la actualización anterior y no altera el gráfico de objetos. Sin embargo, no aclara al consumidor de la API que solo se pueden actualizar los "ID".

En este escenario, ¿qué enfoque se recomienda?

Answer 1

En mi opinión, debe permanecer con la misma estructura para las solicitudes GET y PUT. ¿Por qué? Porque es bastante común mapear datos JSON/XML en objetos, y la mayoría (si no todos) del software que hace la asignación real funcionan mejor si el esquema JSON es siempre el mismo.

Así que su servicio web debe aceptar un siguiente código JSON:

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

Sin embargo, no hay que tener en cuenta el nombre del país y puede centrarse sólo en la Identificación del país.