Incluye

TL;DR: Utiliza una cadena de consulta como ?include=field_comments.uid para incluir todas las entidades referenciadas por field_comments y todas las entidades referenciadas por uid en esas entidades.

JSON:API te ayuda a eliminar solicitudes HTTP permitiéndote especificar rutas de relaciones que deseas incluir en el documento de respuesta. ¿Cómo?

Obteniendo recursos individuales

Obtener un artículo

Imagina que tienes un artículo con dos comentarios y cada uno de esos comentarios tiene el mismo autor. Para obtener todos estos datos sin includes, primero harías una solicitud a GET /jsonapi/node/article/some-random-uuid:

{
  "data": {
    "type": "node--article",
    "id": "some-random-uuid",
    "relationships": {
      "field_comments": {
        "links": {
          "related": {
            "href": "https://my.example.com/node/article/some-random-uuid/field_comments"
          }
        }
      }
    }
  }
}

Obtener comentarios

Luego, harías una solicitud a GET /node/article/some-random-uuid/field_comments:

{
  "data": [{
    "type": "comment",
    "id": "one-random-uuid",
    "relationships": {
      "uid": {
        "links": {
          "related": {
            "href": "https://my.example.com/comment/one-random-uuid/uid"
          }
        }
      }
    }
  }, {
    "type": "comment",
    "id": "two-random-uuid",
    "relationships": {
      "uid": {
        "links": {
          "related": {
            "href": "https://my.example.com/comment/two-random-uuid/uid"
          }
        }
      }
    }
  }
]
}

Obtener usuarios

Y de nuevo, necesitarías hacer dos solicitudes más a /comment/one-random-uuid/uid y /comment/two-random-uuid/uid. Podemos ver que la segunda solicitud es completamente innecesaria porque sabemos que el autor de ambos comentarios es el mismo en nuestro ejemplo.

¿Entonces, cómo pueden ayudar los includes?

Obtener todo de una vez usando include

¡Es fácil! Simplemente agregando un parámetro de consulta a la URL original con los nombres de los campos de relación que deseas incluir, el servidor sabrá que debe buscar todo por ti y agregarlo al documento de respuesta original.

En nuestro ejemplo, la URL de la solicitud sería GET /jsonapi/node/article/some-random-uuid?include=field_comments.uid. En otras palabras, estás diciendo: "por favor, agrega los objetos recurso para el campo field_comments en el artículo, luego también agrega los objetos recurso para el campo uid de los comentarios que hace referencia". Estos "caminos de relación" pueden ser tan largos como desees, ¡no hay límite!

El documento de respuesta que recibirías del servidor sería:

{
  "data": {
    "type": "node--article",
    "id": "some-random-uuid",
    "relationships": {
      "field_comments": {
        "data": [{
          "type": "comment",
          "id": "one-random-uuid"
        }, {
          "type": "comment",
          "id": "two-random-uuid"
        }],
        "links": {
          "related": {
            "href": "https://my.example.com/node/article/some-random-uuid/field_comments"
          }
        }
      }
    }
  },
  "included": [{
    "type": "comment",
    "id": "one-random-uuid",
    "relationships": {
      "uid": {
        "data": [{
          "type": "user",
          "id": "another-random-uuid"
        }],
        "links": {
          "related": {
            "href": "https://my.example.com/comment/one-random-uuid/uid"
          }
        }
      }
    }
  }, {
    "type": "comment",
    "id": "another-random-uuid",
    "relationships": {
      "uid": {
        "data": [{
          "type": "user",
          "id": "one-random-uuid"
        }],
        "links": {
          "related": {
            "href": "https://my.example.com/comment/two-random-uuid/uid"
          }
        }
      }
    }
  }, {
    "type": "user",
    "id": "another-random-uuid",
    "attributes": {
      "name": "c0wb0yC0d3r"
    }
  }]
}

¿No es genial? ¡Obtenemos todos los datos en una sola solicitud! Observa que el objeto recurso de usuario solo se incluye una vez, aunque se referencia dos veces. Esto mantiene bajo el tamaño de la respuesta. También nota cómo ahora hay una clave data en cada objeto de relación. Eso te permite correlacionar los objetos recurso incluidos con los objetos recurso que los referencian.

¿Cuándo usar include?

Hablando del tamaño de la respuesta... en este ejemplo, nos ahorramos tiempo al obtener todos los recursos en una sola solicitud. Sin embargo, en ciertas circunstancias, incluir objetos recurso relacionados hará que el tamaño de la respuesta sea bastante grande y/o el tiempo hasta el primer byte muy lento. En ese caso, podría ser mejor hacer varias solicitudes en paralelo.

Include para colecciones y relaciones

Finalmente, el parámetro de consulta include también está soportado en recursos de colección y relación. Los includes en colecciones pueden ahorrarte muchas solicitudes adicionales.

Ejemplo de include para colección

Obtener includes para una colección podría verse así: GET /jsonapi/node/article?include=uid. Los objetos incluidos están separados de data (array en lugar de objeto) como se muestra a continuación.

{
  "data": [{...}],
  "included": [{
    "type": "user",
    "id": "another-random-uuid",
    "attributes": {
      "name": "c0wb0yC0d3r"
    }
  }]
}

Artículo de la Documentación de Drupal.