API REST: incluya detalles de objetos relacionados o simplemente ID

Question

¿Cuál es la mejor práctica de diseño?

Si tengo el objeto A y contiene algunos objetos relacionados, por ejemplo, tengo un objeto de automóvil y sus varios tipos.

¿Debo bajo petición api.example.org/cars/1 responden simplemente con identificaciones a esos recursos (por lo que si alguien necesita detalles acerca de ellos se requiere otra llamada API en api.example.org/type/1)

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

o proporcionar detalles sobre esos recursos, así

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

O proporcione un parámetro opcional como "displayAll" y luego una matriz con los nombres de los parámetros que deben recuperarse en una llamada API (en este caso tipos).

Answer 1

Esto toca uno de los principios básicos de REST llamado HATEOAS (Hypermedia como el motor del estado de la aplicación).

Los ID de objeto son inútiles y sin sentido para los clientes. ¿Qué haces con ellos? Aliméntalos a una función de búsqueda? ¿Construir un nuevo URI con ellos anexados al final del mismo? Llame a un número 1-800 y pregunte qué hacer con ellos. Imprimir en papel y enviarlos por correo a una agencia del gobierno que ayuda a los clientes de la API a encontrar sus próximos pasos.

Simplemente devuelva el URI completo, todo el tiempo. La ID que se le da al cliente siempre debe ser el URI, es algo que identifica de forma única el recurso en cuestión y puede usarse para recuperarlo, actualizarlo o eliminarlo.

Answer 2

Prefiero la versión sin parámetros de la opción 1, pero preferiría algo donde se devuelva la ubicación del recurso de tipo, de modo que el cliente pueda elegir si desea recuperar esos recursos.

De lo contrario, no estamos navegando por los documentos. Por el contrario, estaríamos confiando en algunos datos fuera de banda, como conocer la ruta al tipo de antemano.

{ 
    "id": 1, 
    "name": "Some Car", 
    "types": [ 
     { 
      "location": "api.example.org/type/1" 
     }, 
     { 
      "location": "api.example.org/type/2" 
     } 
    ] 
}