Include параметр

Кратко (TL;DR): Используйте строку запроса вида ?include=field_comments.uid, чтобы включить все сущности, на которые ссылается field_comments, а также все сущности, на которые ссылается uid в этих сущностях!

JSON:API позволяет сократить количество HTTP-запросов, позволяя указать пути связей, которые вы хотите включить в документ ответа. Как это работает?

Получение одиночных ресурсов

Получение статьи

Допустим, у вас есть статья с двумя комментариями, и у обоих комментариев — один и тот же автор. Чтобы получить все эти данные без include, сначала нужно выполнить запрос 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"
          }
        }
      }
    }
  }
}

Получение комментариев

Затем — запрос по адресу 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"
          }
        }
      }
    }
  }]
}

Получение пользователей

И затем ещё два запроса — к /comment/one-random-uuid/uid и /comment/two-random-uuid/uid. Однако второй запрос будет избыточным, ведь автор у комментариев один и тот же.

Как нам поможет include?

Получение всего сразу с помощью include

Просто добавьте параметр запроса к URL: ?include=field_comments.uid. Это укажет серверу добавить в ответ все сущности, на которые ссылается field_comments, и все сущности, на которые ссылается uid у этих комментариев.

Запрос: GET /jsonapi/node/article/some-random-uuid?include=field_comments.uid

Ответ от сервера будет выглядеть так:

{
  "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"
    }
  }]
}

Круто, правда? Все данные получены одним запросом! Обратите внимание, что объект пользователя включён только один раз, даже если он упоминается дважды — это снижает размер ответа. Также у каждого объекта связи появился ключ data, позволяющий связать включённые сущности с их источниками.

Когда использовать include?

Хотя include позволяет получить всё сразу, это может значительно увеличить размер ответа или замедлить его генерацию. В некоторых случаях лучше делать параллельные запросы.

Include для коллекций и связей

Параметр include поддерживается и в коллекциях, и в ресурсах-связях. Использование include в коллекциях может сэкономить множество запросов.

Пример include для коллекции

Запрос: GET /jsonapi/node/article?include=uid

Ответ будет выглядеть примерно так:

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

Статья с сайта Drupal Documentation.